Metadata-Version: 2.4
Name: politicians-tui
Version: 0.2.0
Summary: Terminal UI for U.S. House and Senate stock disclosures (Prixe API).
Author-email: Mike Coriolan <mike.coriolan@gmail.com>
License: Unlicense
Project-URL: Homepage, https://github.com/prixe-api/politicians-tui
Project-URL: Repository, https://github.com/prixe-api/politicians-tui
Project-URL: Issues, https://github.com/prixe-api/politicians-tui/issues
Keywords: tui,textual,congress,stocks,disclosures,house,senate,prixe
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: Public Domain
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.80
Requires-Dist: httpx>=0.27
Dynamic: license-file

<p align="center">
  <img src="./assets/logo.svg" alt="politicians-tui seal" width="180" height="180">
</p>

<h1 align="center">politicians-tui</h1>

A terminal UI for U.S. House and Senate stock disclosures, powered by the
[Prixe Politicians API](https://prixe.io).

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](https://textual.textualize.io).

```
┌─ 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](https://prixe.io) 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

```sh
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.)

```sh
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:

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

Once published:

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

A `PKGBUILD` lives at [`packaging/aur/PKGBUILD`](packaging/aur/PKGBUILD).

### Windows

```powershell
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:

```sh
politicians-tui
```

---

## Running

```sh
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

```sh
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](./LICENSE) — 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](https://prixe.io), which wraps the
  House Clerk and Senate eFD disclosure feeds.
- **TUI framework** — [Textual](https://textual.textualize.io) by Textualize.
