termradar 0.3.0__tar.gz

termradar-0.3.0/.gitignore

@@ -0,0 +1,34 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Tooling
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# User configuration (never commit)
+config.toml

termradar-0.3.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-05
+
+### Added
+
+- adsb.lol v2 as default live aircraft provider (`--aircraft-provider opensky` for OpenSky)
+- ADSBDB enrichment for routes and airlines (replaces adsb.lol routeset in CLI)
+- ICAO callsign prefix airline inference when enrichment has no airline
+- Top-five nearby aircraft list with numbered radar markers (`1`–`5`)
+- Rate limits: 5 s min / 5 s default refresh, 30 ADSBDB req/min, enrichment TTL cache
+- Nominatim 1 req/s throttle; legacy `refresh_seconds < 5` auto-upgraded on load
+- Local time display via `timezonefinder` and optional `timezone` in config
+- README demo GIF and VHS tape (`docs/assets/demo-quick.*`)
+
+### Changed
+
+- Right panel: **CLOSEST** detail + **NEARBY** compact list (title: NEARBY AIRCRAFT)
+- Radar marker collision handling (offsets when on ring dots or overlapping)
+- Airline display shortens trailing ` Airlines` / ` Air Lines`
+- Documentation overhaul for providers, internal limits, and usage
+- README quick start includes `pip install termradar`
+- Provider User-Agent strings track package `__version__`
+
+### Fixed
+
+- OpenSky HTTP 429 at aggressive refresh (adsb.lol default + minimum 5 s refresh)
+- ADSBDB HTTP 404 logged as debug, not terminal warning
+- ADSBDB route lookup falls back to callsign endpoint when aircraft hex lookup misses
+- Aircraft markers skipped on ring dots
+
+### Dependencies
+
+- Added `timezonefinder` for coordinate → timezone lookup
+
+## [0.2.0] - 2026-07-05
+
+### Added
+
+- Live terminal UI with Rich panels, radar visualization, and nearest-aircraft panel
+- `RadarSession` live refresh loop with configurable interval
+- CLI overrides: `--location`, `--radius` / `--radius-km`, `--refresh` (current run only)
+- Testable `radar_to_grid()` coordinate mapping and ASCII radar canvas
+- Graceful handling of missing aircraft metadata in the UI
+- Stale snapshot display when aircraft provider temporarily fails
+- PyPI-ready project metadata and local wheel build validation
+
+### Changed
+
+- `termradar` runs a live refresh loop instead of a single scan
+- Route provider accepts HTTP 201 responses from adsb.lol
+- Improved first-run onboarding with refresh interval prompt
+
+### Fixed
+
+- Empty adsb.lol route responses (HTTP 201, no body) no longer log false "malformed" warnings
+- Terminal display clears screen before Live render to avoid duplicate headers
+
+### Dependencies
+
+- Added `rich` for terminal layout and live display
+
+## [0.1.0] - 2026-07-05
+
+### Added
+
+- Core radar engine, providers, config storage, CLI, and tests
+
+[Unreleased]: https://github.com/rusty3699/termradar/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/rusty3699/termradar/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/rusty3699/termradar/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/rusty3699/termradar/releases/tag/v0.1.0

termradar-0.3.0/LICENSE

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

termradar-0.3.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: termradar
+Version: 0.3.0
+Summary: See what's flying above you - live aircraft radar for your terminal
+Project-URL: Homepage, https://github.com/rusty3699/termradar
+Project-URL: Repository, https://github.com/rusty3699/termradar
+Project-URL: Documentation, https://github.com/rusty3699/termradar/tree/main/docs
+Project-URL: Issues, https://github.com/rusty3699/termradar/issues
+Author: Anish Tipnis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ads-b,aircraft,aviation,cli,flight-tracking,radar,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: rich>=13.7
+Requires-Dist: timezonefinder>=6.5
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TermRadar
+
+**See what's flying above you - without leaving your terminal.**
+
+![TermRadar live demo](docs/assets/demo-quick.gif)
+
+TermRadar is a lightweight live aircraft radar for developers, programmers, and aviation enthusiasts.
+
+You're coding, you hear an aircraft overhead, or spot something from the window. Instead of opening a browser or reaching for a flight-tracking app, open a terminal and run:
+
+```bash
+termradar
+```
+
+You get a live radar centered on your location: nearby callsigns, distance, bearing, speed, altitude, and route info when available. Use it for the quick answer, then jump to another tracker when you want deeper details.
+
+> **One radar engine. Multiple displays.**
+
+The core is display-agnostic. Today: a polished terminal UI. Planned: Raspberry Pi fullscreen and small displays.
+
+## Quick start
+
+```bash
+pip install termradar
+termradar
+```
+
+From source:
+
+```bash
+git clone https://github.com/rusty3699/termradar.git
+cd termradar
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+termradar
+```
+
+First run: enter a location, pick a geocoding result, set radius and refresh. Later runs reuse saved settings. Press **Ctrl+C** to exit.
+
+Config: `~/.config/termradar/config.toml` on Linux (platformdirs on macOS and Windows — see [ARCHITECTURE.md](docs/ARCHITECTURE.md)).
+
+## What you get
+
+| Available now | Planned |
+|---------------|---------|
+| Live terminal radar (default 5 s refresh) | Raspberry Pi fullscreen display |
+| Numbered radar markers + top-five nearby list | OLED / e-paper displays |
+| Closest-aircraft detail panel | Local ADS-B receivers |
+| adsb.lol live aircraft (default) | Alerts and notifications |
+| ADSBDB route/airline enrichment | Web UI |
+| Nominatim geocoding, local timezone | |
+| OpenSky via `--aircraft-provider opensky` | |
+
+**Requirements:** Python 3.11+, network access. Works on Linux, macOS, Windows, and Raspberry Pi.
+
+## Usage
+
+```bash
+termradar --location "Andheri, Mumbai"  # temporary location (this run only)
+termradar --radius 25                   # search radius in km
+termradar --refresh 10                  # refresh interval (min 5 s)
+termradar --aircraft-provider opensky   # OpenSky instead of adsb.lol
+termradar --enrichment-limit 10         # max aircraft to enrich per scan
+termradar --reset-location              # re-run setup
+termradar --version
+termradar --help
+```
+
+| Setting | Default | Allowed |
+|---------|---------|---------|
+| Refresh | 5 s | 5-300 s |
+| Radius | 15 km | 1-250 km |
+| Aircraft source | adsb.lol | `adsblol` or `opensky` |
+| Enrichment | 10 nearest | `--enrichment-limit` |
+
+Provider details and internal limits: [docs/DATA_PROVIDERS.md](docs/DATA_PROVIDERS.md)
+
+## How it works
+
+```text
+each refresh (every 5 s by default):
+  1. Fetch aircraft near you          → adsb.lol
+  2. Distance and bearing from you
+  3. Enrich nearest (cache miss only) → ADSBDB
+  4. Draw radar + aircraft panels
+
+setup only (not each refresh):
+  Geocoding → Nominatim
+```
+
+**Data sources:** [adsb.lol](https://adsb.lol) (aircraft), [ADSBDB](https://adsbdb.com) (routes/airlines), [Nominatim](https://www.openstreetmap.org) (geocoding)
+
+## Documentation
+
+| Doc | What it covers |
+|-----|----------------|
+| [CHANGELOG.md](CHANGELOG.md) | Release history |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design, UI layout, code boundaries |
+| [DATA_PROVIDERS.md](docs/DATA_PROVIDERS.md) | APIs, internal limits, caching |
+| [ROADMAP.md](docs/ROADMAP.md) | What's next |
+| [DEVELOPMENT.md](docs/DEVELOPMENT.md) | Tests, lint, packaging |
+
+## License
+
+MIT - see [LICENSE](LICENSE).
+
+---
+
+Made with <3 Anish

termradar-0.3.0/README.md

@@ -0,0 +1,110 @@
+# TermRadar
+
+**See what's flying above you - without leaving your terminal.**
+
+![TermRadar live demo](docs/assets/demo-quick.gif)
+
+TermRadar is a lightweight live aircraft radar for developers, programmers, and aviation enthusiasts.
+
+You're coding, you hear an aircraft overhead, or spot something from the window. Instead of opening a browser or reaching for a flight-tracking app, open a terminal and run:
+
+```bash
+termradar
+```
+
+You get a live radar centered on your location: nearby callsigns, distance, bearing, speed, altitude, and route info when available. Use it for the quick answer, then jump to another tracker when you want deeper details.
+
+> **One radar engine. Multiple displays.**
+
+The core is display-agnostic. Today: a polished terminal UI. Planned: Raspberry Pi fullscreen and small displays.
+
+## Quick start
+
+```bash
+pip install termradar
+termradar
+```
+
+From source:
+
+```bash
+git clone https://github.com/rusty3699/termradar.git
+cd termradar
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+termradar
+```
+
+First run: enter a location, pick a geocoding result, set radius and refresh. Later runs reuse saved settings. Press **Ctrl+C** to exit.
+
+Config: `~/.config/termradar/config.toml` on Linux (platformdirs on macOS and Windows — see [ARCHITECTURE.md](docs/ARCHITECTURE.md)).
+
+## What you get
+
+| Available now | Planned |
+|---------------|---------|
+| Live terminal radar (default 5 s refresh) | Raspberry Pi fullscreen display |
+| Numbered radar markers + top-five nearby list | OLED / e-paper displays |
+| Closest-aircraft detail panel | Local ADS-B receivers |
+| adsb.lol live aircraft (default) | Alerts and notifications |
+| ADSBDB route/airline enrichment | Web UI |
+| Nominatim geocoding, local timezone | |
+| OpenSky via `--aircraft-provider opensky` | |
+
+**Requirements:** Python 3.11+, network access. Works on Linux, macOS, Windows, and Raspberry Pi.
+
+## Usage
+
+```bash
+termradar --location "Andheri, Mumbai"  # temporary location (this run only)
+termradar --radius 25                   # search radius in km
+termradar --refresh 10                  # refresh interval (min 5 s)
+termradar --aircraft-provider opensky   # OpenSky instead of adsb.lol
+termradar --enrichment-limit 10         # max aircraft to enrich per scan
+termradar --reset-location              # re-run setup
+termradar --version
+termradar --help
+```
+
+| Setting | Default | Allowed |
+|---------|---------|---------|
+| Refresh | 5 s | 5-300 s |
+| Radius | 15 km | 1-250 km |
+| Aircraft source | adsb.lol | `adsblol` or `opensky` |
+| Enrichment | 10 nearest | `--enrichment-limit` |
+
+Provider details and internal limits: [docs/DATA_PROVIDERS.md](docs/DATA_PROVIDERS.md)
+
+## How it works
+
+```text
+each refresh (every 5 s by default):
+  1. Fetch aircraft near you          → adsb.lol
+  2. Distance and bearing from you
+  3. Enrich nearest (cache miss only) → ADSBDB
+  4. Draw radar + aircraft panels
+
+setup only (not each refresh):
+  Geocoding → Nominatim
+```
+
+**Data sources:** [adsb.lol](https://adsb.lol) (aircraft), [ADSBDB](https://adsbdb.com) (routes/airlines), [Nominatim](https://www.openstreetmap.org) (geocoding)
+
+## Documentation
+
+| Doc | What it covers |
+|-----|----------------|
+| [CHANGELOG.md](CHANGELOG.md) | Release history |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design, UI layout, code boundaries |
+| [DATA_PROVIDERS.md](docs/DATA_PROVIDERS.md) | APIs, internal limits, caching |
+| [ROADMAP.md](docs/ROADMAP.md) | What's next |
+| [DEVELOPMENT.md](docs/DEVELOPMENT.md) | Tests, lint, packaging |
+
+## License
+
+MIT - see [LICENSE](LICENSE).
+
+---
+
+Made with <3 Anish

termradar-0.3.0/docs/ARCHITECTURE.md

@@ -0,0 +1,147 @@
+# Architecture
+
+> **One radar engine. Multiple displays.**
+
+The core produces a `RadarSnapshot` on each scan. Renderers draw it; they never fetch data or call external APIs.
+
+## Data flow
+
+```text
+GeocodingProvider          (setup / location override only)
+        ↓
+     Location  (+ timezone)
+        ↓
+AircraftProvider           (every scan - default: adsb.lol)
+        ↓
+   RadarEngine  ◄──── CachedRouteProvider ──► AdsbDbRouteProvider
+        ↓
+   RadarSnapshot
+        ↓
+   RadarSession  →  TerminalView  →  TerminalRenderer
+        ↓
+   Terminal output (Rich live UI)
+```
+
+A future `FullscreenRenderer` (Phase 3, Raspberry Pi) will consume the same `RadarSnapshot`.
+
+## Scan pipeline
+
+```text
+RadarEngine.scan()
+  → fetch aircraft (AdsblolAircraftProvider by default)
+  → distance_km() + bearing_deg() from radar center
+  → filter by radius, sort nearest-first
+  → enrich nearest N aircraft (ADSBDB with callsign fallback, cached, rate-limited)
+  → infer airline from ICAO callsign prefix when still unknown
+  → RadarSnapshot
+```
+
+Geocoding and timezone resolution run only during onboarding, `--reset-location`, or `--location` - **not** on refresh.
+
+## Live display loop
+
+```text
+RadarSession
+  → engine.scan()
+  → build TerminalView (location, snapshot, errors, terminal size)
+  → TerminalRenderer.render()
+  → sleep(refresh_seconds)    # default 5 s, minimum 5 s
+```
+
+`RadarSession` owns the loop and keeps the last good snapshot when a scan fails (stale mode). `TerminalRenderer` is stateless per frame.
+
+## Terminal UI layout
+
+Wide terminals (≥ 72 columns): radar panel left, aircraft panel right.
+
+**Radar panel**
+
+| Symbol | Meaning |
+|--------|---------|
+| `+` | Your location (radar center) |
+| Outer dotted ring | Search radius |
+| Inner dotted ring | Half of search radius |
+| `1`–`5` | Top five nearest aircraft (matches nearby list) |
+| `✈` | Other aircraft in range |
+| `N` `E` `S` `W` | Compass |
+
+Markers use collision offsets when the ideal grid cell is occupied (ring dot, center, or another marker).
+
+**Nearby aircraft panel**
+
+- **CLOSEST** - full detail for nearest aircraft (callsign, airline, route, distance, bearing, speed, altitude)
+- **NEARBY** - compact top-five list: rank, callsign, distance, compass direction
+
+Narrow terminals fall back to a compact aircraft table.
+
+## Package layout
+
+```text
+src/termradar/
+├── cli.py                     # Entry point, onboarding, provider wiring
+├── session.py                 # Live refresh loop
+├── core/
+│   ├── engine.py              # Scan orchestration
+│   ├── models.py              # Location, Aircraft, RadarSnapshot, …
+│   ├── limits.py              # Rate-limit constants
+│   ├── rate_limit.py          # Rolling minute limiter
+│   ├── airline.py             # ICAO prefix → airline inference
+│   ├── distance.py / bearing.py
+│   ├── location.py / timezone.py
+│   └── …
+├── providers/
+│   ├── geocoding.py           # Nominatim
+│   ├── aircraft.py            # adsb.lol + OpenSky
+│   ├── adsbdb.py              # ADSBDB enrichment
+│   └── routes.py              # CachedRouteProvider, adsb.lol routeset
+├── config/storage.py          # TOML load/save, validation
+└── renderers/
+    ├── formatting.py          # Display strings
+    ├── bearing_display.py     # Compass labels
+    ├── location_display.py    # Short location header
+    ├── radar_coords.py        # Polar → grid
+    ├── radar_canvas.py        # ASCII radar + markers
+    ├── terminal_ui.py         # Rich layout
+    ├── terminal_view.py       # Per-frame view model
+    └── time_display.py        # Local time in location timezone
+```
+
+## Boundaries
+
+| Layer | Does | Does not |
+|-------|------|----------|
+| Providers | HTTP, parsing, caching, rate limiting | Display, geometry |
+| `RadarEngine` | Fetch, filter, sort, enrich | Terminal drawing |
+| `CachedRouteProvider` | TTL cache + 30/min cap | Aircraft positions |
+| `TerminalRenderer` | Layout, radar, formatting | API calls |
+| `radar_to_grid()` | Bearing/distance → grid cell | Fetch or enrich |
+
+## Error handling
+
+| Failure | Behaviour |
+|---------|-----------|
+| Aircraft provider down | Error state; last snapshot shown as stale if available |
+| ADSBDB miss / 404 | Aircraft shown; airline may come from callsign prefix |
+| Enrichment rate limit | Skip remaining lookups this scan; retry later |
+| Missing altitude / route | Graceful fallbacks (`-`, `Unknown airline`, `Route unavailable`) |
+| Ctrl+C | Clean exit |
+
+## Configuration
+
+Stored at `~/.config/termradar/config.toml` (platformdirs).
+
+| Key | Default | Notes |
+|-----|---------|-------|
+| `location.*` | - | Set during onboarding |
+| `radar.radius_km` | 15 | 1–250 km |
+| `radar.refresh_seconds` | 5 | 5–300; values < 5 upgraded on load |
+
+CLI overrides (`--location`, `--radius`, `--refresh`, `--aircraft-provider`, `--enrichment-limit`) apply to the current run only unless `--reset-location` re-saves config.
+
+## Internal limits and caching
+
+See [DATA_PROVIDERS.md](DATA_PROVIDERS.md) for full detail. Summary:
+
+- **Refresh:** 5 s default and minimum → one adsb.lol request per cycle
+- **Enrichment:** 30 ADSBDB requests/minute max, 10 nearest aircraft per scan, 12 h / 30 min cache
+- **Geocoding:** 1 Nominatim request/second, setup only