fed-debt 0.1.0__tar.gz

fed_debt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xorn the first
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fed_debt-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: fed-debt
+Version: 0.1.0
+Summary: Check the current US federal debt to the penny
+Author-email: xorn the first <x0rn@gitlab.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/x0rn/fed-debt
+Project-URL: Repository, https://gitlab.com/x0rn/fed-debt
+Project-URL: Bug Tracker, https://gitlab.com/x0rn/fed-debt/-/issues
+Keywords: treasury,debt,us-debt,finance
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Intended Audience :: End Users/Desktop
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Requires-Dist: rich
+Provides-Extra: ticker
+Requires-Dist: windows-curses; sys_platform == "win32" and extra == "ticker"
+Dynamic: license-file
+
+# fed-debt 🇺🇸
+
+Check the current US federal debt, to the penny.
+
+```
+$ fed-debt
+$39,828,435,390,891.55
+
+$ fed-debt --verbose
+               US Federal Debt — 2026-08-04
+┌──────────────────────────────┬──────────────────────┐
+│ Metric                       │              Amount   │
+├──────────────────────────────┼──────────────────────┤
+│ Total Public Debt Outstanding │ $39,828,435,390,891.55 │
+│ Debt Held by the Public       │ $32,100,703,256,953.12 │
+│ Intragovernmental Holdings    │  $7,727,732,133,938.43 │
+│ Debt per US Citizen           │            $118,890.85 │
+└──────────────────────────────┴──────────────────────┘
+```
+
+## Install
+
+### From PyPI (recommended)
+
+```bash
+pip install fed-debt
+```
+
+Or with ticker support (requires `windows-curses` on Windows):
+
+```bash
+pip install "fed-debt[ticker]"
+```
+
+### From source
+
+```bash
+git clone https://gitlab.com/x0rn/fed-debt.git
+cd fed-debt
+py -m pip install -e .
+```
+
+Or for the ticker:
+
+```bash
+py -m pip install -e ".[ticker]"
+```
+
+## Usage
+
+| Command                | What it does                                    |
+|------------------------|-------------------------------------------------|
+| `fed-debt`             | Prints the latest total debt to the penny       |
+| `fed-debt --verbose`   | Detailed breakdown table with per-citizen debt  |
+| `fed-debt --ticker`    | Opens a small live-updating ticker window       |
+| `fed-debt --version`   | Prints version number                           |
+| `fed-debt --help`      | Shows usage                                     |
+
+### Ticker
+
+The `--ticker` flag opens a thin, 3-line curses window that shows a
+**continuously incrementing** debt counter. Instead of polling the API
+every few seconds (wasteful — the data only updates once a day at
+3:00 PM ET), it:
+
+1. Fetches the latest official reading on startup
+2. Estimates the per-second growth from recent history (~$1.3B/day)
+3. Interpolates the current value in real-time
+
+Press `q` to quit, `r` to force a re-sync with the Treasury API.
+
+## Data Source
+
+U.S. Treasury Fiscal Data — [Debt to the Penny](https://fiscaldata.treasury.gov/datasets/debt-to-the-penny)
+endpoint, updated daily at 3:00 PM ET.
+
+## Future
+
+- `--chart` — terminal-based historical charts (via `plotext`)
+- `--since` — see the debt on a specific past date
+- GUI/web backend using the same `api.py` module

fed_debt-0.1.0/README.md

@@ -0,0 +1,81 @@
+# fed-debt 🇺🇸
+
+Check the current US federal debt, to the penny.
+
+```
+$ fed-debt
+$39,828,435,390,891.55
+
+$ fed-debt --verbose
+               US Federal Debt — 2026-08-04
+┌──────────────────────────────┬──────────────────────┐
+│ Metric                       │              Amount   │
+├──────────────────────────────┼──────────────────────┤
+│ Total Public Debt Outstanding │ $39,828,435,390,891.55 │
+│ Debt Held by the Public       │ $32,100,703,256,953.12 │
+│ Intragovernmental Holdings    │  $7,727,732,133,938.43 │
+│ Debt per US Citizen           │            $118,890.85 │
+└──────────────────────────────┴──────────────────────┘
+```
+
+## Install
+
+### From PyPI (recommended)
+
+```bash
+pip install fed-debt
+```
+
+Or with ticker support (requires `windows-curses` on Windows):
+
+```bash
+pip install "fed-debt[ticker]"
+```
+
+### From source
+
+```bash
+git clone https://gitlab.com/x0rn/fed-debt.git
+cd fed-debt
+py -m pip install -e .
+```
+
+Or for the ticker:
+
+```bash
+py -m pip install -e ".[ticker]"
+```
+
+## Usage
+
+| Command                | What it does                                    |
+|------------------------|-------------------------------------------------|
+| `fed-debt`             | Prints the latest total debt to the penny       |
+| `fed-debt --verbose`   | Detailed breakdown table with per-citizen debt  |
+| `fed-debt --ticker`    | Opens a small live-updating ticker window       |
+| `fed-debt --version`   | Prints version number                           |
+| `fed-debt --help`      | Shows usage                                     |
+
+### Ticker
+
+The `--ticker` flag opens a thin, 3-line curses window that shows a
+**continuously incrementing** debt counter. Instead of polling the API
+every few seconds (wasteful — the data only updates once a day at
+3:00 PM ET), it:
+
+1. Fetches the latest official reading on startup
+2. Estimates the per-second growth from recent history (~$1.3B/day)
+3. Interpolates the current value in real-time
+
+Press `q` to quit, `r` to force a re-sync with the Treasury API.
+
+## Data Source
+
+U.S. Treasury Fiscal Data — [Debt to the Penny](https://fiscaldata.treasury.gov/datasets/debt-to-the-penny)
+endpoint, updated daily at 3:00 PM ET.
+
+## Future
+
+- `--chart` — terminal-based historical charts (via `plotext`)
+- `--since` — see the debt on a specific past date
+- GUI/web backend using the same `api.py` module

fed_debt-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fed-debt"
+version = "0.1.0"
+description = "Check the current US federal debt to the penny"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "xorn the first", email = "x0rn@gitlab.com"},
+]
+keywords = ["treasury", "debt", "us-debt", "finance"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial",
+    "Intended Audience :: End Users/Desktop",
+]
+
+dependencies = [
+    "httpx",
+    "rich",
+]
+
+[project.optional-dependencies]
+ticker = ["windows-curses; sys_platform == 'win32'"]
+
+[project.urls]
+Homepage = "https://gitlab.com/x0rn/fed-debt"
+Repository = "https://gitlab.com/x0rn/fed-debt"
+"Bug Tracker" = "https://gitlab.com/x0rn/fed-debt/-/issues"
+
+[project.scripts]
+fed-debt = "fed_debt.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

fed_debt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fed_debt-0.1.0/src/fed_debt/__init__.py

@@ -0,0 +1,7 @@
+"""fed-debt: Check the current US federal debt to the penny."""
+
+__version__ = "0.1.0"
+
+# Rough US population estimate (used for per-capita calculations).
+# Source: Census Bureau quick facts (~335M as of 2025-2026).
+US_POPULATION = 335_000_000

fed_debt-0.1.0/src/fed_debt/__main__.py

@@ -0,0 +1,6 @@
+"""python -m fed_debt entry point."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fed_debt-0.1.0/src/fed_debt/api.py

@@ -0,0 +1,137 @@
+"""Fetch US federal debt data from the Treasury Fiscal Data API."""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime
+from typing import Any
+
+import httpx
+
+BASE_URL = (
+    "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"
+)
+ENDPOINT = "/v2/accounting/od/debt_to_penny"
+
+# Seconds in a full day (used for real-time ticker interpolation)
+SECONDS_PER_DAY = 86_400
+
+
+@dataclasses.dataclass(frozen=True)
+class DebtSnapshot:
+    """A single official debt reading from the Treasury."""
+
+    record_date: datetime.date
+    tot_pub_debt_out_amt: float
+    debt_held_public_amt: float
+    intragov_hold_amt: float
+
+    @property
+    def debt_per_citizen(self) -> float:
+        from fed_debt import US_POPULATION
+        return self.tot_pub_debt_out_amt / US_POPULATION
+
+    def format_dollar(self, value: float) -> str:
+        """Format a dollar amount with commas and 2 decimal places."""
+        return f"${value:,.2f}"
+
+    def total_dollar(self) -> str:
+        return self.format_dollar(self.tot_pub_debt_out_amt)
+
+    def public_dollar(self) -> str:
+        return self.format_dollar(self.debt_held_public_amt)
+
+    def intragov_dollar(self) -> str:
+        return self.format_dollar(self.intragov_hold_amt)
+
+    def per_citizen_dollar(self) -> str:
+        return self.format_dollar(self.debt_per_citizen)
+
+    def __str__(self) -> str:
+        return self.total_dollar()
+
+
+class DebtClient:
+    """Client for the Treasury Fiscal Data API."""
+
+    def __init__(self, timeout: float = 15.0) -> None:
+        self._client = httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> DebtClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Public methods
+    # ------------------------------------------------------------------
+
+    def latest(self) -> DebtSnapshot:
+        """Fetch the single most recent debt record."""
+        raw = self._fetch(params={
+            "sort": "-record_date",
+            "page[size]": 1,
+        })
+        return self._parse_row(raw["data"][0])
+
+    def last_n(self, n: int) -> list[DebtSnapshot]:
+        """Fetch the *n* most recent debt records (newest first)."""
+        raw = self._fetch(params={
+            "sort": "-record_date",
+            "page[size]": n,
+        })
+        return [self._parse_row(row) for row in raw["data"]]
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _fetch(self, params: dict[str, Any]) -> dict[str, Any]:
+        url = BASE_URL + ENDPOINT
+        resp = self._client.get(url, params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    @staticmethod
+    def _parse_row(row: dict[str, str]) -> DebtSnapshot:
+        return DebtSnapshot(
+            record_date=datetime.date.fromisoformat(row["record_date"]),
+            tot_pub_debt_out_amt=float(row["tot_pub_debt_out_amt"]),
+            debt_held_public_amt=float(row["debt_held_public_amt"]),
+            intragov_hold_amt=float(row["intragov_hold_amt"]),
+        )
+
+    # ------------------------------------------------------------------
+    # Ticker helpers: compute a per-second growth rate
+    # ------------------------------------------------------------------
+
+    def daily_increase(self, n_days: int = 2) -> float:
+        """Return the average *daily* increase over the last *n_days*.
+
+        Fetches ``n_days + 1`` records so we can compute deltas between
+        consecutive business-day readings, then returns the mean daily
+        change in dollars.
+        """
+        records = self.last_n(n_days + 1)
+        if len(records) < 2:
+            return 0.0
+        deltas = []
+        for i in range(len(records) - 1):
+            delta = (
+                records[i].tot_pub_debt_out_amt
+                - records[i + 1].tot_pub_debt_out_amt
+            )
+            # Only count positive deltas (the debt grows)
+            if delta > 0:
+                deltas.append(delta)
+        if not deltas:
+            return 0.0
+        return sum(deltas) / len(deltas)
+
+    def per_second_increase(self, n_days: int = 5) -> float:
+        """Return the average *per-second* increase in dollars."""
+        return self.daily_increase(n_days) / SECONDS_PER_DAY

fed_debt-0.1.0/src/fed_debt/cli.py

@@ -0,0 +1,116 @@
+"""Main CLI entry point for fed-debt."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import NoReturn
+
+from . import __version__
+from .api import DebtClient
+from .ticker import run_ticker
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fed-debt",
+        description="Show the current US federal debt, to the penny.",
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Show a detailed breakdown including public vs intragovernmental "
+             "holdings and debt per citizen.",
+    )
+    parser.add_argument(
+        "--ticker", "-t",
+        action="store_true",
+        help="Open a small, continuously updating debt ticker window.",
+    )
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="Print the version number and exit.",
+    )
+    return parser
+
+
+def print_verbose(snapshot: "DebtSnapshot") -> None:
+    """Print a Rich-formatted detail table."""
+    try:
+        from rich.console import Console
+        from rich.table import Table
+    except ImportError:
+        # Fallback: plain-text output
+        print(f"Record date:          {snapshot.record_date}")
+        print(f"Total debt:           {snapshot.total_dollar()}")
+        print(f"Held by the public:   {snapshot.public_dollar()}")
+        print(f"Intragovernmental:    {snapshot.intragov_dollar()}")
+        print(f"Per US citizen:       {snapshot.per_citizen_dollar()}")
+        print()
+        print(
+            "Data from the U.S. Treasury Fiscal Data API. "
+            "Updated at end of each business day with the "
+            "prior business day's figures."
+        )
+        return
+
+    console = Console()
+    table = Table(title=f"US Federal Debt — {snapshot.record_date}")
+
+    table.add_column("Metric", style="cyan", no_wrap=True)
+    table.add_column("Amount", style="bold green", justify="right")
+
+    table.add_row("Total Public Debt Outstanding", snapshot.total_dollar())
+    table.add_row("Debt Held by the Public", snapshot.public_dollar())
+    table.add_row("Intragovernmental Holdings", snapshot.intragov_dollar())
+    table.add_row("Debt per US Citizen", snapshot.per_citizen_dollar())
+
+    console.print(table)
+    console.print(
+        "[dim]Data from the U.S. Treasury Fiscal Data API. "
+        "Updated at end of each business day with the prior "
+        "business day's figures.[/dim]"
+    )
+
+
+def print_brief(snapshot: "DebtSnapshot") -> None:
+    """Print just the dollar amount, with optional Rich styling."""
+    try:
+        from rich.console import Console
+        console = Console()
+        console.print(f"[bold green]{snapshot.total_dollar()}[/bold green]")
+    except ImportError:
+        print(snapshot.total_dollar())
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        print(f"fed-debt v{__version__}")
+        return 0
+
+    if args.ticker:
+        return run_ticker()
+
+    # Normal mode: fetch and display the latest debt
+    try:
+        client = DebtClient()
+        snapshot = client.latest()
+        client.close()
+    except Exception as exc:
+        print(f"Error fetching debt data: {exc}", file=sys.stderr)
+        return 1
+
+    if args.verbose:
+        print_verbose(snapshot)
+    else:
+        print_brief(snapshot)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fed_debt-0.1.0/src/fed_debt/ticker.py

@@ -0,0 +1,163 @@
+"""Curses-based live debt ticker window.
+
+Usage
+-----
+    from fed_debt.ticker import run_ticker
+    run_ticker()         # opens the curses window
+"""
+
+from __future__ import annotations
+
+import datetime
+import time
+from typing import Any
+
+from .api import DebtClient, DebtSnapshot
+
+# ── constants ────────────────────────────────────────────────────────
+REFRESH_INTERVAL = 1.0         # seconds between display updates
+SYNC_INTERVAL = 3600.0         # re-fetch official data every hour
+SECONDS_PER_DAY = 86_400.0
+
+# Coordinates of the three lines in the ticker window
+LINE_DATE = 0
+LINE_VALUE = 1
+LINE_HELP = 2
+
+WINDOW_HEIGHT = 3
+
+
+def _format_float(value: float) -> str:
+    """Format a large dollar figure with commas and two decimals."""
+    return f"${value:,.2f}"
+
+
+def _compute_current(
+    snapshot: DebtSnapshot,
+    per_second: float,
+    elapsed: float,
+) -> float:
+    """Interpolate the current debt based on the last official snapshot.
+
+    Parameters
+    ----------
+    snapshot :
+        The most recent official reading.
+    per_second :
+        Estimated per-second increase (dollars).
+    elapsed :
+        Number of seconds since the official snapshot's record date
+        (specifically, since midnight of that date — a reasonable
+        approximation).
+    """
+    return snapshot.tot_pub_debt_out_amt + (per_second * elapsed)
+
+
+def _seconds_since_midnight(d: datetime.date) -> float:
+    """How many seconds have passed since midnight UTC of *d*."""
+    then = datetime.datetime(
+        d.year, d.month, d.day, tzinfo=datetime.timezone.utc,
+    )
+    now = datetime.datetime.now(datetime.timezone.utc)
+    return (now - then).total_seconds()
+
+
+def run_ticker() -> int:
+    """Open the curses debt-ticker and block until the user quits.
+
+    Returns 0 on clean exit, 1 on error.
+    """
+    # ── bootstrap data ─────────────────────────────────────────────
+    try:
+        client = DebtClient()
+        snapshot = client.latest()
+        per_second = client.per_second_increase(n_days=5)
+        client.close()
+    except Exception as exc:
+        print(f"Error fetching initial debt data: {exc}")
+        return 1
+
+    last_sync = time.monotonic()
+    # Estimate seconds since midnight of the record date
+    elapsed = _seconds_since_midnight(snapshot.record_date)
+
+    # ── curses setup ────────────────────────────────────────────────
+    import curses
+
+    def _main(stdscr: Any) -> None:
+        nonlocal snapshot, per_second, last_sync, elapsed
+
+        curses.curs_set(0)               # hide cursor
+        stdscr.nodelay(True)              # non-blocking getch()
+        stdscr.timeout(int(REFRESH_INTERVAL * 1000))
+
+        while True:
+            now = time.monotonic()
+
+            # ── periodic re-sync with the API ─────────────────────
+            if now - last_sync >= SYNC_INTERVAL:
+                try:
+                    cli = DebtClient()
+                    fresh = cli.latest()
+                    fresh_ps = cli.per_second_increase(n_days=5)
+                    cli.close()
+                    # Only update if the record date actually changed
+                    if fresh.record_date != snapshot.record_date:
+                        snapshot = fresh
+                        per_second = fresh_ps
+                        elapsed = _seconds_since_midnight(
+                            snapshot.record_date,
+                        )
+                    last_sync = now
+                except Exception:
+                    pass   # keep going with stale data
+
+            # ── compute interpolated value ─────────────────────────
+            elapsed = _seconds_since_midnight(snapshot.record_date)
+            current = _compute_current(snapshot, per_second, elapsed)
+
+            # ── render ─────────────────────────────────────────────
+            height, width = stdscr.getmaxyx()
+
+            # Date line
+            date_str = f" Record date: {snapshot.record_date}  "
+            stdscr.addstr(LINE_DATE, 0, date_str[: width - 1])
+
+            # Value line (centred if possible)
+            val_str = _format_float(current)
+            x = max(0, (width - len(val_str)) // 2)
+            stdscr.addstr(LINE_VALUE, x, val_str[: width - x - 1])
+
+            # Help line
+            help_str = " [q] quit  [r] refresh  "
+            stdscr.addstr(LINE_HELP, 0, help_str[: width - 1])
+
+            stdscr.refresh()
+
+            # ── keyboard handling ──────────────────────────────────
+            key = stdscr.getch()
+            if key in (ord("q"), ord("Q")):
+                break
+            if key in (ord("r"), ord("R")):
+                # Force re-sync now
+                try:
+                    cli = DebtClient()
+                    fresh = cli.latest()
+                    fresh_ps = cli.per_second_increase(n_days=5)
+                    cli.close()
+                    if fresh.record_date != snapshot.record_date:
+                        snapshot = fresh
+                        per_second = fresh_ps
+                        elapsed = _seconds_since_midnight(
+                            snapshot.record_date,
+                        )
+                    last_sync = now
+                except Exception:
+                    pass
+
+    try:
+        curses.wrapper(_main)
+    except KeyboardInterrupt:
+        pass
+
+    return 0

fed_debt-0.1.0/src/fed_debt.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: fed-debt
+Version: 0.1.0
+Summary: Check the current US federal debt to the penny
+Author-email: xorn the first <x0rn@gitlab.com>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/x0rn/fed-debt
+Project-URL: Repository, https://gitlab.com/x0rn/fed-debt
+Project-URL: Bug Tracker, https://gitlab.com/x0rn/fed-debt/-/issues
+Keywords: treasury,debt,us-debt,finance
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Intended Audience :: End Users/Desktop
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Requires-Dist: rich
+Provides-Extra: ticker
+Requires-Dist: windows-curses; sys_platform == "win32" and extra == "ticker"
+Dynamic: license-file
+
+# fed-debt 🇺🇸
+
+Check the current US federal debt, to the penny.
+
+```
+$ fed-debt
+$39,828,435,390,891.55
+
+$ fed-debt --verbose
+               US Federal Debt — 2026-08-04
+┌──────────────────────────────┬──────────────────────┐
+│ Metric                       │              Amount   │
+├──────────────────────────────┼──────────────────────┤
+│ Total Public Debt Outstanding │ $39,828,435,390,891.55 │
+│ Debt Held by the Public       │ $32,100,703,256,953.12 │
+│ Intragovernmental Holdings    │  $7,727,732,133,938.43 │
+│ Debt per US Citizen           │            $118,890.85 │
+└──────────────────────────────┴──────────────────────┘
+```
+
+## Install
+
+### From PyPI (recommended)
+
+```bash
+pip install fed-debt
+```
+
+Or with ticker support (requires `windows-curses` on Windows):
+
+```bash
+pip install "fed-debt[ticker]"
+```
+
+### From source
+
+```bash
+git clone https://gitlab.com/x0rn/fed-debt.git
+cd fed-debt
+py -m pip install -e .
+```
+
+Or for the ticker:
+
+```bash
+py -m pip install -e ".[ticker]"
+```
+
+## Usage
+
+| Command                | What it does                                    |
+|------------------------|-------------------------------------------------|
+| `fed-debt`             | Prints the latest total debt to the penny       |
+| `fed-debt --verbose`   | Detailed breakdown table with per-citizen debt  |
+| `fed-debt --ticker`    | Opens a small live-updating ticker window       |
+| `fed-debt --version`   | Prints version number                           |
+| `fed-debt --help`      | Shows usage                                     |
+
+### Ticker
+
+The `--ticker` flag opens a thin, 3-line curses window that shows a
+**continuously incrementing** debt counter. Instead of polling the API
+every few seconds (wasteful — the data only updates once a day at
+3:00 PM ET), it:
+
+1. Fetches the latest official reading on startup
+2. Estimates the per-second growth from recent history (~$1.3B/day)
+3. Interpolates the current value in real-time
+
+Press `q` to quit, `r` to force a re-sync with the Treasury API.
+
+## Data Source
+
+U.S. Treasury Fiscal Data — [Debt to the Penny](https://fiscaldata.treasury.gov/datasets/debt-to-the-penny)
+endpoint, updated daily at 3:00 PM ET.
+
+## Future
+
+- `--chart` — terminal-based historical charts (via `plotext`)
+- `--since` — see the debt on a specific past date
+- GUI/web backend using the same `api.py` module

fed_debt-0.1.0/src/fed_debt.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/fed_debt/__init__.py
+src/fed_debt/__main__.py
+src/fed_debt/api.py
+src/fed_debt/cli.py
+src/fed_debt/ticker.py
+src/fed_debt.egg-info/PKG-INFO
+src/fed_debt.egg-info/SOURCES.txt
+src/fed_debt.egg-info/dependency_links.txt
+src/fed_debt.egg-info/entry_points.txt
+src/fed_debt.egg-info/requires.txt
+src/fed_debt.egg-info/top_level.txt

fed_debt-0.1.0/src/fed_debt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fed_debt-0.1.0/src/fed_debt.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fed-debt = fed_debt.cli:main

fed_debt-0.1.0/src/fed_debt.egg-info/requires.txt

@@ -0,0 +1,7 @@
+httpx
+rich
+
+[ticker]
+
+[ticker:sys_platform == "win32"]
+windows-curses

fed_debt-0.1.0/src/fed_debt.egg-info/top_level.txt

@@ -0,0 +1 @@
+fed_debt