terrascope 0.1.0__tar.gz

terrascope-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.DS_Store
+
+.venv/
+venv/
+
+build/
+dist/
+*.egg-info/
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

terrascope-0.1.0/LICENSE

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

terrascope-0.1.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.5
+Name: terrascope
+Version: 0.1.0
+Summary: A Braille terminal map with live weather, aircraft, and earthquake layers.
+Project-URL: Homepage, https://github.com/a-shygun/terrascope
+Project-URL: Repository, https://github.com/a-shygun/terrascope
+Project-URL: Issues, https://github.com/a-shygun/terrascope/issues
+Author-email: Amir Shygun <a-shygun@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: braille,curses,flight-tracking,map,opensky,terminal,tui,weather
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+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 :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0
+Requires-Dist: pyshp>=2.3
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# terrascope
+
+[![CI](https://github.com/a-shygun/terrascope/actions/workflows/ci.yml/badge.svg)](https://github.com/a-shygun/terrascope/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/terrascope)](https://pypi.org/project/terrascope/)
+[![Python](https://img.shields.io/pypi/pyversions/terrascope)](https://pypi.org/project/terrascope/)
+[![License](https://img.shields.io/github/license/a-shygun/terrascope)](LICENSE)
+
+`terrascope` is an interactive world map for the terminal. It renders countries,
+place names, live aircraft, city weather, radar/cloud overlays, earthquakes, and
+day/night bands with `curses`, Unicode Braille cells, and terminal colors.
+
+The app is intentionally lightweight at install time. Large map data is
+downloaded into a user cache the first time it is needed, then reused on later
+runs.
+
+Country names and abbreviations, plus airport names and locations, are bundled
+from Natural Earth so they are available offline without a first-run download.
+
+<!-- TODO: Add a short terminal demo GIF at docs/images/terrascope-demo.gif. -->
+<!-- TODO: Add screenshots for the map, weather, planes, and time tabs under docs/images/. -->
+
+## Status
+
+This project is early-stage software. The core map, tabs, keyboard/mouse
+navigation, live layers, and cache handling are implemented, but APIs and visual
+details may still change.
+
+## Requirements
+
+- Python 3.10 or newer on macOS or Linux/Unix
+- A UTF-8 terminal
+- A terminal with 256-color or true-color support for the best appearance
+- Network access for first-run map downloads and live data layers (optional)
+
+Python dependencies are declared in `pyproject.toml`:
+
+- `numpy`
+- `Pillow`
+- `PyYAML`
+
+## Installation
+
+For normal use:
+
+```bash
+pipx install terrascope
+terrascope
+```
+
+### Package managers
+
+Terrascope also includes recipes for Nix and Homebrew:
+
+```bash
+# Nix, from a Terrascope checkout
+nix run ./packaging/nix
+
+# Homebrew, after adding the tap
+brew install a-shygun/terrascope/terrascope
+```
+
+PyPI publishing is automated for version tags. The Nix recipe lives in
+`packaging/nix/`, and the Homebrew formula lives in `Formula/`; update their
+version references when preparing a release.
+
+For local development:
+
+```bash
+git clone https://github.com/a-shygun/terrascope.git
+cd terrascope
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+terrascope
+```
+
+You can also run it from a checkout without installing the console script:
+
+```bash
+PYTHONPATH=src python3 -m terrascope
+```
+
+## First Run and Cache
+
+On first launch, `terrascope` downloads Natural Earth GeoJSON files into:
+
+```text
+$XDG_CACHE_HOME/terrascope
+```
+
+If `XDG_CACHE_HOME` is not set, the default is:
+
+```text
+~/.cache/terrascope
+```
+
+Useful cache commands:
+
+```bash
+terrascope --show-paths
+terrascope --clear-cache
+terrascope --offline
+```
+
+## Common Options
+
+```bash
+terrascope --help                         # all options and defaults
+terrascope --tab weather --offline        # open a tab using cached data only
+terrascope --no-radar --no-airports       # disable optional overlays
+terrascope --disable-layer night          # start with a layer disabled
+terrascope --config ~/terrascope.yaml     # load additional settings
+terrascope --set 'map.zoom.max=128'       # override one setting for this run
+terrascope --show-paths                   # show cache and config locations
+terrascope --clear-cache                  # remove cached downloads and API data
+terrascope --dump-config                  # print effective settings
+terrascope --list-keys                    # show active keyboard shortcuts
+```
+
+CLI flags override configuration for the current run. `--set` overrides flags;
+see `terrascope --help` for the full precedence order and every available
+option.
+
+During first-run downloads the terminal UI shows a loading message before the
+map appears. Errors and background warnings are written to the log file shown by
+`terrascope --show-paths`, so stray output does not corrupt the curses screen.
+
+## Controls
+
+| Input | Action |
+| --- | --- |
+| `1`-`9` | Switch tabs |
+| `WASD` or arrow keys | Pan |
+| `+` / `-` | Zoom in / out |
+| `0` | Reset view |
+| Mouse drag | Pan |
+| Mouse wheel | Zoom |
+| Mouse click | Select a marker or map label |
+| `<` / `>` | Step through overlapping selections |
+| `/` | Search |
+| `O` | Open filter prompt |
+| `H` | Show or hide the bottom panel |
+| `?` | Open the welcome/help modal |
+| `Esc` | Close prompts or clear selection/filter state |
+| `Q` | Quit |
+
+Layer-specific keys:
+
+| Key | Layer |
+| --- | --- |
+| `P` | Flights |
+| `K` | Airports on the planes tab |
+| `C` | City weather labels |
+| `E` | Earthquakes |
+| `N` | Day/night layer |
+| `L` | Day/night tint/fill mode |
+| `[` / `]` | Time slider where available |
+
+Run this for the effective key list:
+
+```bash
+terrascope --list-keys
+```
+
+## Tabs And Layers
+
+- `MAP`: base world map with country, province/state, and city detail as
+  zoom allows.
+- `TIME`: day/night bands, sun information, moon information, and timezone
+  selection.
+- `WEATHER`: city weather, forecast panel, radar/cloud overlay, and USGS
+  earthquakes.
+- `PLANES`: OpenSky aircraft positions, trails, categories, and Natural Earth
+  airport markers.
+
+## Configuration
+
+Defaults live in:
+
+```text
+~/.config/terrascope/default.yaml
+```
+
+On first launch, Terrascope copies the bundled defaults to this location and
+loads that user-owned copy. Existing files are kept across upgrades. If
+`XDG_CONFIG_HOME` is set, Terrascope uses `$XDG_CONFIG_HOME/terrascope/default.yaml`.
+
+You can override settings without editing the package:
+
+```bash
+terrascope --config ~/terrascope.yaml
+terrascope --set 'map.zoom.max=128'
+terrascope --set 'map.land_color="#101018"'
+```
+
+Inspect the final merged config:
+
+```bash
+terrascope --dump-config
+```
+
+Important environment variables:
+
+| Variable | Meaning |
+| --- | --- |
+| `terrascope_OFFLINE=1` | Disable live network requests |
+| `terrascope_CONFIG=/path/file.yaml` | Load a config file before CLI flags |
+| `terrascope_LIBREWXR_URL=https://...` | Override the radar/cloud server |
+| `XDG_CACHE_HOME=/path` | Change the default cache root |
+
+## Project Layout
+
+```text
+src/terrascope/
+  __main__.py              python -m terrascope entry point
+  assets/                  default configuration and bundled reference data
+  core/
+    app/                   app lifecycle, input, mouse, and rendering mixins
+    ui/                    colors, layout, dialogs, and map drawing
+    cli.py config.py       command-line and settings validation
+    mapdata.py world.py    geographic data and map state
+  layers/
+    basemap/               country outlines, labels, and map detail
+    daynight/              day/night rendering and astronomy calculations
+    flights/               OpenSky API, cache, formatting, and aircraft layer
+    weather/               weather, radar, forecast, and earthquake modules
+```
+
+The public console entry point is:
+
+```toml
+terrascope = "terrascope.__main__:run"
+```
+
+## Data Sources
+
+- Natural Earth: country and province/state outlines, populated places
+- OpenSky Network: aircraft positions
+- Open-Meteo: city weather and forecasts
+- LibreWXR-compatible public endpoint: radar/cloud tiles
+- USGS GeoJSON feeds: earthquakes
+- NOAA/Meeus-style calculations in code: day/night and moon information
+
+Bundled reference data is from [Natural Earth 50m Cultural Vectors](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/), which is public domain.
+
+Each source has its own availability and rate-limit behavior. Use `--offline`
+when you want to run only from cached data.
+
+Terrascope has no telemetry or analytics. When live layers are enabled, network
+requests go to the configured data providers. Weather requests include the
+coordinates of displayed cities; providers also receive your IP address and
+the Terrascope User-Agent. `--offline` disables live requests.
+
+## Development Checks
+
+Basic syntax check:
+
+```bash
+python3 -m compileall -q src/terrascope
+```
+
+If dependencies are installed, a quick import smoke test is:
+
+```bash
+PYTHONPATH=src python3 -c "from terrascope.core.registry import build_layers; print([l.name for l in build_layers()])"
+```
+
+## Releasing
+
+Versioned tags build and publish the wheel and source distribution to PyPI.
+Update the separate Homebrew tap after PyPI confirms the release. See
+[docs/RELEASING.md](docs/RELEASING.md) for the release and Git steps.
+
+## License
+
+MIT. See `LICENSE`.

terrascope-0.1.0/README.md

@@ -0,0 +1,276 @@
+# terrascope
+
+[![CI](https://github.com/a-shygun/terrascope/actions/workflows/ci.yml/badge.svg)](https://github.com/a-shygun/terrascope/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/terrascope)](https://pypi.org/project/terrascope/)
+[![Python](https://img.shields.io/pypi/pyversions/terrascope)](https://pypi.org/project/terrascope/)
+[![License](https://img.shields.io/github/license/a-shygun/terrascope)](LICENSE)
+
+`terrascope` is an interactive world map for the terminal. It renders countries,
+place names, live aircraft, city weather, radar/cloud overlays, earthquakes, and
+day/night bands with `curses`, Unicode Braille cells, and terminal colors.
+
+The app is intentionally lightweight at install time. Large map data is
+downloaded into a user cache the first time it is needed, then reused on later
+runs.
+
+Country names and abbreviations, plus airport names and locations, are bundled
+from Natural Earth so they are available offline without a first-run download.
+
+<!-- TODO: Add a short terminal demo GIF at docs/images/terrascope-demo.gif. -->
+<!-- TODO: Add screenshots for the map, weather, planes, and time tabs under docs/images/. -->
+
+## Status
+
+This project is early-stage software. The core map, tabs, keyboard/mouse
+navigation, live layers, and cache handling are implemented, but APIs and visual
+details may still change.
+
+## Requirements
+
+- Python 3.10 or newer on macOS or Linux/Unix
+- A UTF-8 terminal
+- A terminal with 256-color or true-color support for the best appearance
+- Network access for first-run map downloads and live data layers (optional)
+
+Python dependencies are declared in `pyproject.toml`:
+
+- `numpy`
+- `Pillow`
+- `PyYAML`
+
+## Installation
+
+For normal use:
+
+```bash
+pipx install terrascope
+terrascope
+```
+
+### Package managers
+
+Terrascope also includes recipes for Nix and Homebrew:
+
+```bash
+# Nix, from a Terrascope checkout
+nix run ./packaging/nix
+
+# Homebrew, after adding the tap
+brew install a-shygun/terrascope/terrascope
+```
+
+PyPI publishing is automated for version tags. The Nix recipe lives in
+`packaging/nix/`, and the Homebrew formula lives in `Formula/`; update their
+version references when preparing a release.
+
+For local development:
+
+```bash
+git clone https://github.com/a-shygun/terrascope.git
+cd terrascope
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+terrascope
+```
+
+You can also run it from a checkout without installing the console script:
+
+```bash
+PYTHONPATH=src python3 -m terrascope
+```
+
+## First Run and Cache
+
+On first launch, `terrascope` downloads Natural Earth GeoJSON files into:
+
+```text
+$XDG_CACHE_HOME/terrascope
+```
+
+If `XDG_CACHE_HOME` is not set, the default is:
+
+```text
+~/.cache/terrascope
+```
+
+Useful cache commands:
+
+```bash
+terrascope --show-paths
+terrascope --clear-cache
+terrascope --offline
+```
+
+## Common Options
+
+```bash
+terrascope --help                         # all options and defaults
+terrascope --tab weather --offline        # open a tab using cached data only
+terrascope --no-radar --no-airports       # disable optional overlays
+terrascope --disable-layer night          # start with a layer disabled
+terrascope --config ~/terrascope.yaml     # load additional settings
+terrascope --set 'map.zoom.max=128'       # override one setting for this run
+terrascope --show-paths                   # show cache and config locations
+terrascope --clear-cache                  # remove cached downloads and API data
+terrascope --dump-config                  # print effective settings
+terrascope --list-keys                    # show active keyboard shortcuts
+```
+
+CLI flags override configuration for the current run. `--set` overrides flags;
+see `terrascope --help` for the full precedence order and every available
+option.
+
+During first-run downloads the terminal UI shows a loading message before the
+map appears. Errors and background warnings are written to the log file shown by
+`terrascope --show-paths`, so stray output does not corrupt the curses screen.
+
+## Controls
+
+| Input | Action |
+| --- | --- |
+| `1`-`9` | Switch tabs |
+| `WASD` or arrow keys | Pan |
+| `+` / `-` | Zoom in / out |
+| `0` | Reset view |
+| Mouse drag | Pan |
+| Mouse wheel | Zoom |
+| Mouse click | Select a marker or map label |
+| `<` / `>` | Step through overlapping selections |
+| `/` | Search |
+| `O` | Open filter prompt |
+| `H` | Show or hide the bottom panel |
+| `?` | Open the welcome/help modal |
+| `Esc` | Close prompts or clear selection/filter state |
+| `Q` | Quit |
+
+Layer-specific keys:
+
+| Key | Layer |
+| --- | --- |
+| `P` | Flights |
+| `K` | Airports on the planes tab |
+| `C` | City weather labels |
+| `E` | Earthquakes |
+| `N` | Day/night layer |
+| `L` | Day/night tint/fill mode |
+| `[` / `]` | Time slider where available |
+
+Run this for the effective key list:
+
+```bash
+terrascope --list-keys
+```
+
+## Tabs And Layers
+
+- `MAP`: base world map with country, province/state, and city detail as
+  zoom allows.
+- `TIME`: day/night bands, sun information, moon information, and timezone
+  selection.
+- `WEATHER`: city weather, forecast panel, radar/cloud overlay, and USGS
+  earthquakes.
+- `PLANES`: OpenSky aircraft positions, trails, categories, and Natural Earth
+  airport markers.
+
+## Configuration
+
+Defaults live in:
+
+```text
+~/.config/terrascope/default.yaml
+```
+
+On first launch, Terrascope copies the bundled defaults to this location and
+loads that user-owned copy. Existing files are kept across upgrades. If
+`XDG_CONFIG_HOME` is set, Terrascope uses `$XDG_CONFIG_HOME/terrascope/default.yaml`.
+
+You can override settings without editing the package:
+
+```bash
+terrascope --config ~/terrascope.yaml
+terrascope --set 'map.zoom.max=128'
+terrascope --set 'map.land_color="#101018"'
+```
+
+Inspect the final merged config:
+
+```bash
+terrascope --dump-config
+```
+
+Important environment variables:
+
+| Variable | Meaning |
+| --- | --- |
+| `terrascope_OFFLINE=1` | Disable live network requests |
+| `terrascope_CONFIG=/path/file.yaml` | Load a config file before CLI flags |
+| `terrascope_LIBREWXR_URL=https://...` | Override the radar/cloud server |
+| `XDG_CACHE_HOME=/path` | Change the default cache root |
+
+## Project Layout
+
+```text
+src/terrascope/
+  __main__.py              python -m terrascope entry point
+  assets/                  default configuration and bundled reference data
+  core/
+    app/                   app lifecycle, input, mouse, and rendering mixins
+    ui/                    colors, layout, dialogs, and map drawing
+    cli.py config.py       command-line and settings validation
+    mapdata.py world.py    geographic data and map state
+  layers/
+    basemap/               country outlines, labels, and map detail
+    daynight/              day/night rendering and astronomy calculations
+    flights/               OpenSky API, cache, formatting, and aircraft layer
+    weather/               weather, radar, forecast, and earthquake modules
+```
+
+The public console entry point is:
+
+```toml
+terrascope = "terrascope.__main__:run"
+```
+
+## Data Sources
+
+- Natural Earth: country and province/state outlines, populated places
+- OpenSky Network: aircraft positions
+- Open-Meteo: city weather and forecasts
+- LibreWXR-compatible public endpoint: radar/cloud tiles
+- USGS GeoJSON feeds: earthquakes
+- NOAA/Meeus-style calculations in code: day/night and moon information
+
+Bundled reference data is from [Natural Earth 50m Cultural Vectors](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/), which is public domain.
+
+Each source has its own availability and rate-limit behavior. Use `--offline`
+when you want to run only from cached data.
+
+Terrascope has no telemetry or analytics. When live layers are enabled, network
+requests go to the configured data providers. Weather requests include the
+coordinates of displayed cities; providers also receive your IP address and
+the Terrascope User-Agent. `--offline` disables live requests.
+
+## Development Checks
+
+Basic syntax check:
+
+```bash
+python3 -m compileall -q src/terrascope
+```
+
+If dependencies are installed, a quick import smoke test is:
+
+```bash
+PYTHONPATH=src python3 -c "from terrascope.core.registry import build_layers; print([l.name for l in build_layers()])"
+```
+
+## Releasing
+
+Versioned tags build and publish the wheel and source distribution to PyPI.
+Update the separate Homebrew tap after PyPI confirms the release. See
+[docs/RELEASING.md](docs/RELEASING.md) for the release and Git steps.
+
+## License
+
+MIT. See `LICENSE`.

terrascope-0.1.0/docs/RELEASING.md

@@ -0,0 +1,55 @@
+# Release workflow
+
+Use one version and one signed Git tag for every distribution channel. The
+PyPI workflow builds and publishes the sdist and wheel from that tag. Homebrew
+is updated in the separate tap repository after the PyPI release is visible.
+The Nix recipe is maintained here. The Arch recipe is a draft and must not be
+submitted to the AUR until its `SKIP` checksum is replaced with the archive's
+SHA-256.
+
+## One-time setup
+
+1. Create the `pypi` GitHub Actions environment in the repository settings.
+2. On PyPI, configure a Trusted Publisher for this repository and the workflow
+   `.github/workflows/release.yml`, using the `pypi` environment. No PyPI token
+   needs to be stored in GitHub secrets.
+3. Create a Homebrew tap repository (for example,
+   `a-shygun/homebrew-terrascope`) containing `Formula/terrascope.rb`. Keep the
+   formula pointed at the matching version tag.
+
+## Release a version
+
+1. Create a release branch from `main`, update `project.version` in
+   `pyproject.toml`, and update user-facing release notes. Open a pull request
+   and merge it after review.
+2. From the updated `main`, create and push a signed version tag (configure
+   Git tag signing first). For example:
+
+   ```bash
+   git switch main
+   git pull --ff-only
+   git tag -s v0.2.0 -m "Release 0.2.0"
+   git push origin v0.2.0
+   ```
+
+3. The tag starts `.github/workflows/release.yml`. It builds both Python
+   distributions, checks their metadata, then publishes the exact build
+   artifacts to PyPI through Trusted Publishing. Confirm the release appears
+   on PyPI before moving on.
+4. Update `Formula/terrascope.rb` to the new version tag, then copy it into the
+   tap repository. The formula uses the versioned Git tag as its source.
+   Homebrew's `brew bump-formula-pr` can calculate/update these fields and open
+   a pull request; check `brew bump-formula-pr --help` for the current options.
+5. Validate the formula in the tap checkout with `brew audit --strict` and
+   `brew test`, then open and merge the tap pull request. Verify a clean install
+   with `brew install <tap>/terrascope`.
+6. If preparing an Arch package, update `packaging/arch/PKGBUILD`, calculate the
+   SHA-256 of the versioned source archive, replace `SKIP`, then build and review
+   the package before submitting it to the AUR. The Nix recipe reads the package
+   version from `pyproject.toml`; update `packaging/nix/flake.lock` when refreshing
+   nixpkgs.
+
+Do not reuse a published PyPI version or move a release tag. If a release has a
+packaging defect, increment the version and publish a new tag. Keep PyPI
+publishing credentials out of the repository; the workflow uses a PyPI
+Trusted Publisher with the `pypi` environment.