terminex 0.4.0__tar.gz

terminex-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 johnd
+
+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.

terminex-0.4.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: terminex
+Version: 0.4.0
+Summary: Terminal dashboard for live FX, crypto, and commodity prices
+License: MIT License
+        
+        Copyright (c) 2026 johnd
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/johnd/terminex
+Project-URL: Issues, https://github.com/johnd/terminex/issues
+Keywords: terminal,tui,forex,crypto,commodities,dashboard
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Dynamic: license-file
+
+# terminex
+
+A terminal dashboard for live prices across three asset classes:
+
+- **FX** — top 25 most-traded currencies (BIS triennial survey)
+- **Crypto** — top 25 coins by market cap
+- **Commodities** — metals, energy, and agriculturals futures
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pipx install terminex
+# or, from a local checkout:
+pipx install .
+# or editable for development:
+pip install -e .
+```
+
+## Run
+
+```bash
+terminex
+# or without installing:
+python3 -m terminex
+```
+
+### Keys
+
+| Key       | Action                                              |
+|-----------|-----------------------------------------------------|
+| `1/2/3/4` | Switch to FX / Crypto / Commodities / Watchlist tab |
+| `j` / `k` | Move highlighted row down / up                      |
+| `g` / `G` | Jump to first / last row                            |
+| `s`       | Cycle sort key: default → 24h → price               |
+| `S`       | Toggle sort direction                               |
+| `/`       | Filter by symbol or name substring (live)           |
+| `Esc`     | Clear filter / close help / close converter        |
+| `w`       | Toggle watchlist pin for the highlighted row        |
+| `~`       | Toggle sparkline column                             |
+| `c`       | Open cross-rate calculator                          |
+| `a`       | Create alert on highlighted row                     |
+| `A`       | List / delete alerts                                |
+| `?`       | Toggle help overlay                                 |
+| `r`       | Force refresh the current tab                       |
+| `q`       | Quit                                                |
+
+### CLI options
+
+- `--base USD` — FX base currency (default: `USD`)
+- `--tab fx|crypto|commodity|watchlist` — tab to start on
+- `--interval 10` — refresh interval in seconds
+
+### Filter
+
+Press `/` to enter live-filter mode and start typing. The table filters
+as you type against both symbol and name. Enter exits filter mode
+(keeping the filter active); Esc cancels and clears.
+
+### Sparklines
+
+Press `~` to toggle a 20-point sparkline column showing recent price
+movement. Series are built up from live polls — newly-started series
+start empty and fill in over time. Green means net up, red means net
+down. The column hides the natural units but makes trend-shape obvious
+at a glance.
+
+### Cross-rate calculator
+
+Press `c` to open an interactive conversion prompt that resolves across
+all three asset classes via USD pivot. Type expressions like:
+
+```
+1 BTC in EUR
+500 EUR in JPY
+1 GC.F in EUR
+1,000 USD in GBP
+```
+
+Press `Enter` to compute, `Esc` to close. The last 5 results stay
+visible above the prompt. Symbols are whatever is loaded in the
+fx / crypto / commodity tabs (commodity symbols use Stooq notation like
+`GC.F`, `CL.F`).
+
+### Price alerts
+
+Highlight any row and press `a` to open the alert-creation modal. The
+threshold field pre-fills with the current price. While the modal is
+open:
+
+- `0-9` / `.` — edit threshold
+- `<` / `>` — toggle the comparison operator
+- `r` — toggle recurring (one-shot by default)
+- `Enter` — create alert
+- `Esc` — cancel
+
+Alerts fire when the price *crosses* the threshold, not every tick
+while above/below it. On fire: terminal bell, toast in the status
+line, and a desktop notification via `notify-send` (Linux; silently
+skipped if unavailable). Non-recurring alerts auto-deactivate on first
+fire.
+
+Press `A` for the list view — browse all alerts, type an ID and press
+`Enter` to delete. The status bar shows the active-alert count.
+
+Alerts are stored in SQLite at
+`~/.local/share/terminex/terminex.db` (or `$XDG_DATA_HOME/terminex/`)
+and survive across runs.
+
+### Watchlist
+
+Highlight any row on the FX / Crypto / Commodities tabs and press `w` to
+pin it. Press `4` to see all pins across asset classes in a single
+unified view, sortable the same way as any other tab. Pins persist to
+`~/.config/terminex/watchlist.toml` and survive across runs.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests -t .
+```
+
+Stdlib `unittest` only, no extra dependencies. Covers the pure-logic
+modules (converter, alerts DAO & engine, watchlist, filter/sort
+helpers, age formatter).
+
+## Data sources
+
+| Asset       | Provider                          | Key required?   | Notes                           |
+|-------------|-----------------------------------|-----------------|---------------------------------|
+| FX          | `open.er-api.com`                 | no              | updates ~hourly                 |
+| Crypto      | `coingecko.com` (default)         | no              | top 25 by mcap, ~1 min cache    |
+| Crypto      | `rest.coincap.io` (if key set)    | yes (free)      | top 25 by mcap, sub-minute data |
+| Commodities | `stooq.com` (CSV)                 | no              | 14 futures, ~15-min delayed     |
+
+**Crypto tab works out of the box** via CoinGecko's public API. For
+faster / higher-rate data, [grab a free CoinCap API key](https://coincap.io/)
+and export it — terminex will automatically prefer it:
+
+```bash
+export TERMINEX_COINCAP_KEY=your-key-here
+```
+
+Or put it in the config file (see below).
+
+## Config file
+
+terminex looks for `~/.config/terminex/config.toml` (or
+`$XDG_CONFIG_HOME/terminex/config.toml`). All keys optional:
+
+```toml
+base_currency = "USD"
+refresh_interval = 10
+active_tab = "fx"
+
+[providers.crypto]
+api_key = "your-coincap-key"
+```
+
+Environment variables win over config file values.

terminex-0.4.0/README.md

@@ -0,0 +1,161 @@
+# terminex
+
+A terminal dashboard for live prices across three asset classes:
+
+- **FX** — top 25 most-traded currencies (BIS triennial survey)
+- **Crypto** — top 25 coins by market cap
+- **Commodities** — metals, energy, and agriculturals futures
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pipx install terminex
+# or, from a local checkout:
+pipx install .
+# or editable for development:
+pip install -e .
+```
+
+## Run
+
+```bash
+terminex
+# or without installing:
+python3 -m terminex
+```
+
+### Keys
+
+| Key       | Action                                              |
+|-----------|-----------------------------------------------------|
+| `1/2/3/4` | Switch to FX / Crypto / Commodities / Watchlist tab |
+| `j` / `k` | Move highlighted row down / up                      |
+| `g` / `G` | Jump to first / last row                            |
+| `s`       | Cycle sort key: default → 24h → price               |
+| `S`       | Toggle sort direction                               |
+| `/`       | Filter by symbol or name substring (live)           |
+| `Esc`     | Clear filter / close help / close converter        |
+| `w`       | Toggle watchlist pin for the highlighted row        |
+| `~`       | Toggle sparkline column                             |
+| `c`       | Open cross-rate calculator                          |
+| `a`       | Create alert on highlighted row                     |
+| `A`       | List / delete alerts                                |
+| `?`       | Toggle help overlay                                 |
+| `r`       | Force refresh the current tab                       |
+| `q`       | Quit                                                |
+
+### CLI options
+
+- `--base USD` — FX base currency (default: `USD`)
+- `--tab fx|crypto|commodity|watchlist` — tab to start on
+- `--interval 10` — refresh interval in seconds
+
+### Filter
+
+Press `/` to enter live-filter mode and start typing. The table filters
+as you type against both symbol and name. Enter exits filter mode
+(keeping the filter active); Esc cancels and clears.
+
+### Sparklines
+
+Press `~` to toggle a 20-point sparkline column showing recent price
+movement. Series are built up from live polls — newly-started series
+start empty and fill in over time. Green means net up, red means net
+down. The column hides the natural units but makes trend-shape obvious
+at a glance.
+
+### Cross-rate calculator
+
+Press `c` to open an interactive conversion prompt that resolves across
+all three asset classes via USD pivot. Type expressions like:
+
+```
+1 BTC in EUR
+500 EUR in JPY
+1 GC.F in EUR
+1,000 USD in GBP
+```
+
+Press `Enter` to compute, `Esc` to close. The last 5 results stay
+visible above the prompt. Symbols are whatever is loaded in the
+fx / crypto / commodity tabs (commodity symbols use Stooq notation like
+`GC.F`, `CL.F`).
+
+### Price alerts
+
+Highlight any row and press `a` to open the alert-creation modal. The
+threshold field pre-fills with the current price. While the modal is
+open:
+
+- `0-9` / `.` — edit threshold
+- `<` / `>` — toggle the comparison operator
+- `r` — toggle recurring (one-shot by default)
+- `Enter` — create alert
+- `Esc` — cancel
+
+Alerts fire when the price *crosses* the threshold, not every tick
+while above/below it. On fire: terminal bell, toast in the status
+line, and a desktop notification via `notify-send` (Linux; silently
+skipped if unavailable). Non-recurring alerts auto-deactivate on first
+fire.
+
+Press `A` for the list view — browse all alerts, type an ID and press
+`Enter` to delete. The status bar shows the active-alert count.
+
+Alerts are stored in SQLite at
+`~/.local/share/terminex/terminex.db` (or `$XDG_DATA_HOME/terminex/`)
+and survive across runs.
+
+### Watchlist
+
+Highlight any row on the FX / Crypto / Commodities tabs and press `w` to
+pin it. Press `4` to see all pins across asset classes in a single
+unified view, sortable the same way as any other tab. Pins persist to
+`~/.config/terminex/watchlist.toml` and survive across runs.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests -t .
+```
+
+Stdlib `unittest` only, no extra dependencies. Covers the pure-logic
+modules (converter, alerts DAO & engine, watchlist, filter/sort
+helpers, age formatter).
+
+## Data sources
+
+| Asset       | Provider                          | Key required?   | Notes                           |
+|-------------|-----------------------------------|-----------------|---------------------------------|
+| FX          | `open.er-api.com`                 | no              | updates ~hourly                 |
+| Crypto      | `coingecko.com` (default)         | no              | top 25 by mcap, ~1 min cache    |
+| Crypto      | `rest.coincap.io` (if key set)    | yes (free)      | top 25 by mcap, sub-minute data |
+| Commodities | `stooq.com` (CSV)                 | no              | 14 futures, ~15-min delayed     |
+
+**Crypto tab works out of the box** via CoinGecko's public API. For
+faster / higher-rate data, [grab a free CoinCap API key](https://coincap.io/)
+and export it — terminex will automatically prefer it:
+
+```bash
+export TERMINEX_COINCAP_KEY=your-key-here
+```
+
+Or put it in the config file (see below).
+
+## Config file
+
+terminex looks for `~/.config/terminex/config.toml` (or
+`$XDG_CONFIG_HOME/terminex/config.toml`). All keys optional:
+
+```toml
+base_currency = "USD"
+refresh_interval = 10
+active_tab = "fx"
+
+[providers.crypto]
+api_key = "your-coincap-key"
+```
+
+Environment variables win over config file values.

terminex-0.4.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "terminex"
+version = "0.4.0"
+description = "Terminal dashboard for live FX, crypto, and commodity prices"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+keywords = ["terminal", "tui", "forex", "crypto", "commodities", "dashboard"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Terminals",
+]
+dependencies = [
+    "requests>=2.31",
+    "rich>=13.0",
+]
+
+[project.scripts]
+terminex = "terminex.app:main"
+
+[project.urls]
+Homepage = "https://github.com/johnd/terminex"
+Issues = "https://github.com/johnd/terminex/issues"
+
+[tool.setuptools.packages.find]
+include = ["terminex*"]
+exclude = ["tests*"]

terminex-0.4.0/setup.cfg

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

terminex-0.4.0/terminex/__init__.py

@@ -0,0 +1 @@
+"""terminex — live FX rates in the terminal."""

terminex-0.4.0/terminex/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for ``python -m terminex``."""
+
+from __future__ import annotations
+
+import sys
+
+from .app import main
+
+if __name__ == "__main__":
+    sys.exit(main())

terminex-0.4.0/terminex/alert_engine.py

@@ -0,0 +1,69 @@
+"""Alert evaluation against live snapshots.
+
+Holds in-memory ``last_price`` per (asset_class, symbol) to detect
+threshold *crossings* rather than firing every tick while the
+condition stays true.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+
+from . import alerts as alerts_dao
+from .alerts import Alert, _row_to_alert
+from .quote import Snapshot
+
+
+@dataclass(frozen=True)
+class FireEvent:
+    alert: Alert
+    price: float
+
+
+class AlertEngine:
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self.conn = conn
+        self._last_price: dict[tuple[str, str], float] = {}
+
+    def evaluate(self, snapshot: Snapshot, asset_class: str) -> list[FireEvent]:
+        quote_by_sym = {q.symbol: q.price for q in snapshot.quotes}
+        # Only load alerts for this asset_class
+        rows = self.conn.execute(
+            """
+            SELECT * FROM alerts
+            WHERE active = 1 AND asset_class = ?
+            """,
+            (asset_class,),
+        ).fetchall()
+        fires: list[FireEvent] = []
+        for row in rows:
+            alert = _row_to_alert(row)
+            price = quote_by_sym.get(alert.symbol)
+            if price is None:
+                continue
+            key = (asset_class, alert.symbol)
+            prev = self._last_price.get(key)
+            triggered = _is_triggered(alert, price, prev)
+            if triggered:
+                alerts_dao.record_fire(self.conn, alert.id, price)
+                if not alert.recurring:
+                    alerts_dao.deactivate(self.conn, alert.id)
+                fires.append(FireEvent(alert=alert, price=price))
+        # update last-seen prices for every symbol in this snapshot
+        for sym, price in quote_by_sym.items():
+            self._last_price[(asset_class, sym)] = price
+        return fires
+
+
+def _is_triggered(alert: Alert, price: float, prev: float | None) -> bool:
+    if alert.op == ">":
+        if price <= alert.threshold:
+            return False
+        # first observation OR prev did not satisfy the condition
+        return prev is None or prev <= alert.threshold
+    if alert.op == "<":
+        if price >= alert.threshold:
+            return False
+        return prev is None or prev >= alert.threshold
+    return False

terminex-0.4.0/terminex/alerts.py

@@ -0,0 +1,117 @@
+"""Alert dataclass and DAO.
+
+An alert fires when ``price`` crosses ``threshold`` in the ``op``
+direction. Non-recurring alerts auto-deactivate on fire; recurring
+ones stay active (but only fire again after the price leaves the
+triggered region, so we don't spam).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Literal
+
+Op = Literal[">", "<"]
+
+
+@dataclass(frozen=True)
+class Alert:
+    id: int
+    asset_class: str
+    symbol: str
+    op: Op
+    threshold: float
+    recurring: bool
+    active: bool
+    created_at: str
+    last_fired_at: str | None
+
+
+def _now_utc_iso() -> str:
+    return datetime.now(tz=timezone.utc).isoformat(timespec="seconds")
+
+
+def create(
+    conn: sqlite3.Connection,
+    *,
+    asset_class: str,
+    symbol: str,
+    op: Op,
+    threshold: float,
+    recurring: bool = False,
+) -> Alert:
+    cur = conn.execute(
+        """
+        INSERT INTO alerts
+          (asset_class, symbol, op, threshold, recurring, active, created_at)
+        VALUES (?, ?, ?, ?, ?, 1, ?)
+        """,
+        (asset_class, symbol, op, threshold, int(recurring), _now_utc_iso()),
+    )
+    return get(conn, cur.lastrowid)
+
+
+def get(conn: sqlite3.Connection, alert_id: int) -> Alert:
+    row = conn.execute(
+        "SELECT * FROM alerts WHERE id = ?", (alert_id,)
+    ).fetchone()
+    if row is None:
+        raise KeyError(alert_id)
+    return _row_to_alert(row)
+
+
+def list_active(conn: sqlite3.Connection) -> list[Alert]:
+    rows = conn.execute(
+        "SELECT * FROM alerts WHERE active = 1 ORDER BY id"
+    ).fetchall()
+    return [_row_to_alert(r) for r in rows]
+
+
+def list_all(conn: sqlite3.Connection) -> list[Alert]:
+    rows = conn.execute("SELECT * FROM alerts ORDER BY active DESC, id").fetchall()
+    return [_row_to_alert(r) for r in rows]
+
+
+def delete(conn: sqlite3.Connection, alert_id: int) -> bool:
+    cur = conn.execute("DELETE FROM alerts WHERE id = ?", (alert_id,))
+    return cur.rowcount > 0
+
+
+def deactivate(conn: sqlite3.Connection, alert_id: int) -> None:
+    conn.execute("UPDATE alerts SET active = 0 WHERE id = ?", (alert_id,))
+
+
+def record_fire(
+    conn: sqlite3.Connection, alert_id: int, price: float
+) -> None:
+    ts = _now_utc_iso()
+    conn.execute(
+        "INSERT INTO fires (alert_id, fired_at, price) VALUES (?, ?, ?)",
+        (alert_id, ts, price),
+    )
+    conn.execute(
+        "UPDATE alerts SET last_fired_at = ? WHERE id = ?",
+        (ts, alert_id),
+    )
+
+
+def count_active(conn: sqlite3.Connection) -> int:
+    return conn.execute(
+        "SELECT COUNT(*) FROM alerts WHERE active = 1"
+    ).fetchone()[0]
+
+
+def _row_to_alert(row: sqlite3.Row) -> Alert:
+    return Alert(
+        id=row["id"],
+        asset_class=row["asset_class"],
+        symbol=row["symbol"],
+        op=row["op"],
+        threshold=row["threshold"],
+        recurring=bool(row["recurring"]),
+        active=bool(row["active"]),
+        created_at=row["created_at"],
+        last_fired_at=row["last_fired_at"],
+    )