politicians-tui 0.1.0

Terminal UI for U.S. House and Senate stock disclosures (Prixe API).

politicians-tui

A terminal UI for U.S. House and Senate stock disclosures, powered by the Prixe Politicians API.

No browser, no Docker, no framework bloat — just a searchable directory of filers, a live transaction feed, and a one-keystroke holdings drill-down. Built on Textual.

┌─ Politicians ─────────────┬─ Latest transactions (2026) ──────────────────┐
│ /pelosi                   │ Date        Politician         Type  Asset     │
│ ──────────────────────    │ 2026-03-04  Hon. Nancy Pelosi  BUY   NVDA      │
│ Hon. Nancy Pelosi (CA11)  │ 2026-02-28  Hon. Josh …        SELL  AAPL      │
│ Hon. Josh Gottheimer …    │ …                                              │
└───────────────────────────┴────────────────────────────────────────────────┘
 q Quit  / Search  r Refresh  c Clear  h Holdings

Requirements

• Python 3.10+
• A Prixe Pro+ subscription (the app reads PRIXE_API_KEY from .env or the environment).

---

Install

Note: politicians-tui is not yet published to PyPI. Until it is, install from a local clone or directly from GitHub — shown first in each section below. The pipx install politicians-tui shorthand will work once a release is cut.

macOS

brew install pipx
pipx ensurepath

# From a local clone (current)
git clone https://github.com/prixe-api/politicians-tui
pipx install ./politicians-tui

# Or directly from GitHub
pipx install 'git+https://github.com/prixe-api/politicians-tui.git'

# Once published to PyPI
pipx install politicians-tui

Linux (Debian / Ubuntu / Fedora / etc.)

sudo apt install pipx        # Debian / Ubuntu
# or: sudo dnf install pipx  # Fedora
pipx ensurepath

git clone https://github.com/prixe-api/politicians-tui
pipx install ./politicians-tui

Arch Linux (AUR)

Until the package is published to the AUR:

git clone https://github.com/prixe-api/politicians-tui
cd politicians-tui/packaging/aur
makepkg -si

Once published:

yay -S python-politicians-tui
# or with paru:
paru -S python-politicians-tui

A PKGBUILD lives at packaging/aur/PKGBUILD.

Windows

python -m pip install --user pipx
python -m pipx ensurepath

# From a local clone (current)
git clone https://github.com/prixe-api/politicians-tui
pipx install .\politicians-tui

# Or directly from GitHub
pipx install 'git+https://github.com/prixe-api/politicians-tui.git'

Windows Terminal is recommended over the legacy cmd.exe host for proper Unicode and color rendering. PowerShell 7+ works well.

---

Configure

Set your API key in .env (in whatever directory you run from) or export it:

PRIXE_API_KEY=your_key_here

Then run:

politicians-tui

---

Running

politicians-tui                       # both chambers, current year
politicians-tui --chamber house       # House only
politicians-tui --chamber senate      # Senate only
politicians-tui --year 2024           # pin to a specific filing year
politicians-tui --limit-politicians N # cap the directory list to N entries
politicians-tui --test 10             # non-interactive smoke test, then exit

If the current filing year hasn't populated yet, the app falls back through the previous two years automatically.

The scene

Press p on the main screen to play the animated auction scene for the currently-selected filing. Each scene follows one politician through a scripted day of trading: they walk on stage (over a state-themed backdrop), visit the broker's desk, greet them by last name, call out each order, the gavel slams with a *★* impact, and the scene closes with an "ENTERED INTO THE RECORD" epilogue card reading out the filer's own description text — verbatim.

Same-day trades by the same politician are collapsed into one continuous scene. The playback loops into the next filing automatically.

Scene-screen keys: space pause/play, ←/→ step one event, n/b jump to the next/previous filing, esc back to the main feed.

State backdrops ship for CA, CO, FL, MD and a generic Capitol fallback. Adding a state is one entry in scene.py: copy _GENERIC_BACKDROP, repaint a few lines with state motifs, register the postal code in BACKDROPS.

Keybindings

Key	Action
/	Focus the filter input
enter (in filter)	Jump to the politician list
↑ / ↓	Move selection
enter (on a politician)	Load their transactions
p	Play the scene for the selected (or latest) filing
h	Open holdings drill-down for the selected politician
r	Refresh the current view
c	Clear filter, return to the latest feed
esc / q	Close modal / quit

Data coverage

• House — PTR disclosures back to 2008.
• Senate — PTR disclosures back to 2012 (electronic-filing rollout date).
• Senate transactions have state_district unset — the Senate eFD system doesn't expose district data.

Development

git clone https://github.com/prixe-api/politicians-tui
cd politicians-tui
python3 -m venv venv
./venv/bin/pip install -e .
./venv/bin/politicians-tui

Project layout:

src/politicians_tui/
├── __init__.py
├── __main__.py     # CLI entrypoint, .env loader, --test
├── api.py          # Backend protocol + PrixeClient
├── app.py          # Textual app: directory, transaction feed, holdings modal, scene screen
└── scene.py        # Scripted auction scene: ASCII sprites, state backdrops, renderer
packaging/aur/
└── PKGBUILD

Starter issues:

• Additional transaction filters (date range, ticker, amount threshold)
• CSV / JSON export of the current view
• Color-code transaction types, sort toggles on the table columns
• Screen-reader / accessibility pass

License

The Unlicense — released to the public domain. Run it, fork it, sell it, change it, remove attribution, incorporate it into a proprietary product. No warranty of any kind.

Acknowledgements

• Prixe Politicians API — Prixe, which wraps the House Clerk and Senate eFD disclosure feeds.
• TUI framework — Textual by Textualize.