weathr 1.0.0__tar.gz

weathr-1.0.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: weathr
+Version: 1.0.0
+Summary: A fast terminal weather client
+Keywords: weather,cli,terminal,air-quality
+Author: Harshit Pawar
+Author-email: Harshit Pawar <hpchess64@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: msgspec>=0.21.1
+Requires-Dist: platformdirs>=4.11.2
+Requires-Dist: rich>=15.0.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer>=0.27.1
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/harshitpawar64/weather
+Project-URL: Repository, https://github.com/harshitpawar64/weather
+Project-URL: Issues, https://github.com/harshitpawar64/weather/issues
+Project-URL: Changelog, https://github.com/harshitpawar64/weather/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# weather ⛅
+
+[![CI](https://github.com/harshitpawar64/weather/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/harshitpawar64/weather/actions/workflows/ci.yml)
+[![python](https://img.shields.io/badge/Python-3.12_|_3.13_|_3.14-35c555.svg?logo=python&labelColor=31373c&logoColor=skyblue)](https://www.python.org/)
+
+[![uv](https://img.shields.io/badge/uv-black.svg?logo=uv)](https://docs.astral.sh/uv/)
+[![ruff](https://img.shields.io/badge/ruff-black.svg?logo=ruff)](https://docs.astral.sh/ruff/)
+[![ty](https://img.shields.io/badge/ty-black.svg?logo=ty)](https://docs.astral.sh/ty/)
+[![pytest](https://img.shields.io/badge/pytest-black.svg?logo=pytest)](https://docs.pytest.org/)
+
+A fast, beautiful terminal weather client with multi-provider fallbacks, AQI metrics, and smart caching.
+
+![weather demo](assets/demo.gif)
+
+---
+
+## Install
+
+```bash
+# With uv (recommended)
+uv tool install weathr
+
+# With pipx
+pipx install weathr
+```
+
+---
+
+## First-Run Onboarding
+
+On your first launch (or at any time by running `weather setup`), `weather` launches an interactive onboarding flow. It detects your location using IP geolocation, asks to confirm your preferred city, and lets you pick your default unit system.
+
+![onboarding demo](assets/onboarding.gif)
+
+Your preferences are saved locally (`config.toml`). After setup, simply running `weather` displays your local forecast instantly.
+
+---
+
+## Usage
+
+```bash
+# Check current weather + 6-day forecast for your saved location
+weather
+
+# Check weather for any city, landmark, address or postal codes
+weather -l Tokyo
+weather -l "Berlin, Germany"
+weather -l 94103
+
+# Specify total days of forecast (1 to 16 days)
+weather -d 3
+weather -l London -d 10
+
+# Override unit system
+weather --metric     # °C, km/h, mm
+weather --imperial   # °F, mph, in
+
+# Output JSON for scripting
+weather --json
+weather -l "Reykjavik" --json | jq .weather.current.temperature
+
+# Verbose logging
+weather -l "Berlin" -v
+```
+
+---
+
+## CLI Options & Subcommands
+
+### Options
+
+| **Flag**     | **Short** |   **Default**  | **Description**                                 |
+|--------------|:---------:|:--------------:|-------------------------------------------------|
+| `--location` |    `-l`   | Saved location | City, landmark, address or postal codes.        |
+| `--days`     |    `-d`   |       `7`      | Total days of forecast, including today. (1-16) |
+| `--metric`   |           |                | Use metric units (°C, km/h, mm)                 |
+| `--imperial` |           |                | Use imperial units (°F, mph, in)                |
+| `--json`     |           |     `False`    | Output result in JSON format.                   |
+| `--theme`    |    `-t`   |    `default`   | Theme to use for rendering output.              |
+| `--verbose`  |    `-v`   |     `False`    | Enable verbose debug logging.                   |
+| `--version`  |           |                | Show version and exit.                          |
+
+### Default File Paths
+
+| **OS**  | **Config Path (`weather config path`)**             | **Cache Path (`weather cache path`)**     |
+|---------|-----------------------------------------------------|-------------------------------------------|
+| Linux   | `~/.config/weather/config.toml`                     | `~/.cache/weather/cache.bin`              |
+| macOS   | `~/Library/Application Support/weather/config.toml` | `~/Library/Caches/weather/cache.bin`      |
+| Windows | `%LOCALAPPDATA%\weather\config.toml`                | `%LOCALAPPDATA%\weather\Cache\cache.bin`  |
+
+### Cache Management
+
+`weather` maintains a fast binary msgpack cache to eliminate redundant network calls:
+
+```bash
+# View cache file location
+weather cache path
+
+# Remove expired entries (>1 week old)
+weather cache prune
+
+# Wipe the cache entirely
+weather cache clear
+```
+
+### Configuration Management
+
+```bash
+# Run interactive setup at any time
+weather setup
+
+# Display config file path
+weather config path
+```
+
+Config file example (`config.toml`):
+
+```toml
+unit_system = "metric"
+theme = "default"
+
+[location]
+latitude = 37.774929
+longitude = -122.419416
+display_name = "San Francisco, California, United States"
+```
+
+---
+
+## Optional: OpenWeather API Key
+
+`weather` works out of the box with **zero configuration** using Open-Meteo. If you want [OpenWeather](https://openweathermap.org/) as an automatic secondary fallback for Air Quality (AQI) data, [obtain a free API key](https://openweathermap.org/api) and set the `OPENWEATHER_API_KEY` environment variable:
+
+### Linux & macOS (Bash / Zsh)
+
+```bash
+echo 'export OPENWEATHER_API_KEY="your_api_key_here"' >> ~/.bashrc  # or ~/.zshrc
+source ~/.bashrc  # or source ~/.zshrc
+```
+
+### Windows (Powershell)
+
+```powershell
+[System.Environment]::SetEnvironmentVariable('OPENWEATHER_API_KEY', 'your_api_key_here', 'User')
+```
+
+---
+
+## Attributions & Data Sources
+
+This project is powered by several free and open data providers:
+
+- **Weather Forecast**:
+  - [Open-Meteo](https://open-meteo.com/en/docs/) (Weather Forecast API) under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+- **Air Quality**:
+  - [Open-Meteo](https://open-meteo.com/en/docs/air-quality-api/) (Air Quality API) under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+  - [OpenWeather](https://openweathermap.org/) (Air Pollution API).
+- **Geocoding**:
+  - [Nominatim](https://nominatim.org/) (Data © [OpenStreetMap contributors](https://www.openstreetmap.org/copyright)).
+  - [Open-Meteo](https://open-meteo.com/en/docs/geocoding-api/) (Geocoding API) under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+- **IP Geolocation**:
+  - [IPWhoIs](https://ipwhois.io/)
+  - [FreeIPAPI](https://freeipapi.com/)
+  - [CountryIs](https://country.is/)
+  - [IPInfo](https://ipinfo.io/)
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

weathr-1.0.0/README.md

@@ -0,0 +1,172 @@
+# weather ⛅
+
+[![CI](https://github.com/harshitpawar64/weather/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/harshitpawar64/weather/actions/workflows/ci.yml)
+[![python](https://img.shields.io/badge/Python-3.12_|_3.13_|_3.14-35c555.svg?logo=python&labelColor=31373c&logoColor=skyblue)](https://www.python.org/)
+
+[![uv](https://img.shields.io/badge/uv-black.svg?logo=uv)](https://docs.astral.sh/uv/)
+[![ruff](https://img.shields.io/badge/ruff-black.svg?logo=ruff)](https://docs.astral.sh/ruff/)
+[![ty](https://img.shields.io/badge/ty-black.svg?logo=ty)](https://docs.astral.sh/ty/)
+[![pytest](https://img.shields.io/badge/pytest-black.svg?logo=pytest)](https://docs.pytest.org/)
+
+A fast, beautiful terminal weather client with multi-provider fallbacks, AQI metrics, and smart caching.
+
+![weather demo](assets/demo.gif)
+
+---
+
+## Install
+
+```bash
+# With uv (recommended)
+uv tool install weathr
+
+# With pipx
+pipx install weathr
+```
+
+---
+
+## First-Run Onboarding
+
+On your first launch (or at any time by running `weather setup`), `weather` launches an interactive onboarding flow. It detects your location using IP geolocation, asks to confirm your preferred city, and lets you pick your default unit system.
+
+![onboarding demo](assets/onboarding.gif)
+
+Your preferences are saved locally (`config.toml`). After setup, simply running `weather` displays your local forecast instantly.
+
+---
+
+## Usage
+
+```bash
+# Check current weather + 6-day forecast for your saved location
+weather
+
+# Check weather for any city, landmark, address or postal codes
+weather -l Tokyo
+weather -l "Berlin, Germany"
+weather -l 94103
+
+# Specify total days of forecast (1 to 16 days)
+weather -d 3
+weather -l London -d 10
+
+# Override unit system
+weather --metric     # °C, km/h, mm
+weather --imperial   # °F, mph, in
+
+# Output JSON for scripting
+weather --json
+weather -l "Reykjavik" --json | jq .weather.current.temperature
+
+# Verbose logging
+weather -l "Berlin" -v
+```
+
+---
+
+## CLI Options & Subcommands
+
+### Options
+
+| **Flag**     | **Short** |   **Default**  | **Description**                                 |
+|--------------|:---------:|:--------------:|-------------------------------------------------|
+| `--location` |    `-l`   | Saved location | City, landmark, address or postal codes.        |
+| `--days`     |    `-d`   |       `7`      | Total days of forecast, including today. (1-16) |
+| `--metric`   |           |                | Use metric units (°C, km/h, mm)                 |
+| `--imperial` |           |                | Use imperial units (°F, mph, in)                |
+| `--json`     |           |     `False`    | Output result in JSON format.                   |
+| `--theme`    |    `-t`   |    `default`   | Theme to use for rendering output.              |
+| `--verbose`  |    `-v`   |     `False`    | Enable verbose debug logging.                   |
+| `--version`  |           |                | Show version and exit.                          |
+
+### Default File Paths
+
+| **OS**  | **Config Path (`weather config path`)**             | **Cache Path (`weather cache path`)**     |
+|---------|-----------------------------------------------------|-------------------------------------------|
+| Linux   | `~/.config/weather/config.toml`                     | `~/.cache/weather/cache.bin`              |
+| macOS   | `~/Library/Application Support/weather/config.toml` | `~/Library/Caches/weather/cache.bin`      |
+| Windows | `%LOCALAPPDATA%\weather\config.toml`                | `%LOCALAPPDATA%\weather\Cache\cache.bin`  |
+
+### Cache Management
+
+`weather` maintains a fast binary msgpack cache to eliminate redundant network calls:
+
+```bash
+# View cache file location
+weather cache path
+
+# Remove expired entries (>1 week old)
+weather cache prune
+
+# Wipe the cache entirely
+weather cache clear
+```
+
+### Configuration Management
+
+```bash
+# Run interactive setup at any time
+weather setup
+
+# Display config file path
+weather config path
+```
+
+Config file example (`config.toml`):
+
+```toml
+unit_system = "metric"
+theme = "default"
+
+[location]
+latitude = 37.774929
+longitude = -122.419416
+display_name = "San Francisco, California, United States"
+```
+
+---
+
+## Optional: OpenWeather API Key
+
+`weather` works out of the box with **zero configuration** using Open-Meteo. If you want [OpenWeather](https://openweathermap.org/) as an automatic secondary fallback for Air Quality (AQI) data, [obtain a free API key](https://openweathermap.org/api) and set the `OPENWEATHER_API_KEY` environment variable:
+
+### Linux & macOS (Bash / Zsh)
+
+```bash
+echo 'export OPENWEATHER_API_KEY="your_api_key_here"' >> ~/.bashrc  # or ~/.zshrc
+source ~/.bashrc  # or source ~/.zshrc
+```
+
+### Windows (Powershell)
+
+```powershell
+[System.Environment]::SetEnvironmentVariable('OPENWEATHER_API_KEY', 'your_api_key_here', 'User')
+```
+
+---
+
+## Attributions & Data Sources
+
+This project is powered by several free and open data providers:
+
+- **Weather Forecast**:
+  - [Open-Meteo](https://open-meteo.com/en/docs/) (Weather Forecast API) under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+- **Air Quality**:
+  - [Open-Meteo](https://open-meteo.com/en/docs/air-quality-api/) (Air Quality API) under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+  - [OpenWeather](https://openweathermap.org/) (Air Pollution API).
+- **Geocoding**:
+  - [Nominatim](https://nominatim.org/) (Data © [OpenStreetMap contributors](https://www.openstreetmap.org/copyright)).
+  - [Open-Meteo](https://open-meteo.com/en/docs/geocoding-api/) (Geocoding API) under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+- **IP Geolocation**:
+  - [IPWhoIs](https://ipwhois.io/)
+  - [FreeIPAPI](https://freeipapi.com/)
+  - [CountryIs](https://country.is/)
+  - [IPInfo](https://ipinfo.io/)
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

weathr-1.0.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "weathr"
+version = "1.0.0"
+description = "A fast terminal weather client"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "msgspec>=0.21.1",
+    "platformdirs>=4.11.2",
+    "rich>=15.0.0",
+    "tomli-w>=1.2.0",
+    "typer>=0.27.1",
+]
+keywords = [
+    "weather",
+    "cli",
+    "terminal",
+    "air-quality",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+
+[[project.authors]]
+name = "Harshit Pawar"
+email = "hpchess64@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/harshitpawar64/weather"
+Repository = "https://github.com/harshitpawar64/weather"
+Issues = "https://github.com/harshitpawar64/weather/issues"
+Changelog = "https://github.com/harshitpawar64/weather/blob/main/CHANGELOG.md"
+
+[project.scripts]
+weather = "weather.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.2",
+    "ty>=0.0.71",
+]
+
+[tool.uv.build-backend]
+module-name = "weather"
+
+[tool.ruff.format]
+skip-magic-trailing-comma = true
+
+[tool.ruff.lint]
+extend-select = ["I"]
+
+[tool.ruff.lint.isort]
+split-on-trailing-comma = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--cov=weather --cov-report=term-missing --cov-branch -v"

weathr-1.0.0/pyproject.toml.orig

@@ -0,0 +1,66 @@
+[project]
+name = "weathr"
+version = "1.0.0"
+description = "A fast terminal weather client"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Harshit Pawar", email = "hpchess64@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "msgspec>=0.21.1",
+    "platformdirs>=4.11.2",
+    "rich>=15.0.0",
+    "tomli-w>=1.2.0",
+    "typer>=0.27.1",
+]
+keywords = ["weather", "cli", "terminal", "air-quality"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/harshitpawar64/weather"
+Repository = "https://github.com/harshitpawar64/weather"
+Issues = "https://github.com/harshitpawar64/weather/issues"
+Changelog = "https://github.com/harshitpawar64/weather/blob/main/CHANGELOG.md"
+
+[project.scripts]
+weather = "weather.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.2",
+    "ty>=0.0.71",
+]
+
+[tool.uv.build-backend]
+module-name = "weather"
+
+[tool.ruff.format]
+skip-magic-trailing-comma = true
+
+[tool.ruff.lint]
+extend-select = ["I"]
+
+[tool.ruff.lint.isort]
+split-on-trailing-comma = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--cov=weather --cov-report=term-missing --cov-branch -v"

weathr-1.0.0/src/weather/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"  # x-release-please-version

weathr-1.0.0/src/weather/__main__.py

@@ -0,0 +1,4 @@
+from weather.cli import app
+
+if __name__ == "__main__":
+    app()

weathr-1.0.0/src/weather/app.py

@@ -0,0 +1,74 @@
+import asyncio
+
+import httpx
+import msgspec
+
+from weather.cache import Cache
+from weather.config import Config
+from weather.models import Theme, UnitSystem, WeatherResponse
+from weather.onboarding import onboarding
+from weather.services import (
+    AQIService,
+    GeocodingService,
+    GeolocationService,
+    WeatherService,
+)
+from weather.ui.render import render_weather
+
+cache = Cache()
+config = Config()
+
+
+async def run(
+    query: str | None,
+    unit_system: UnitSystem,
+    theme: Theme,
+    days: int,
+    json_output: bool,
+) -> None:
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        if query:
+            geocoder = GeocodingService(client, cache)
+            location = await geocoder.geocode(query)
+        elif config.location:
+            location = config.location
+        else:
+            location, unit_system = await onboarding(
+                GeolocationService(client), GeocodingService(client, cache)
+            )
+
+            config.save(location, unit_system)
+
+        weather_service = WeatherService(client, cache)
+        aqi_service = AQIService(client, cache)
+
+        weather, aqi = await asyncio.gather(
+            weather_service.get_weather(location, unit_system),
+            aqi_service.get_aqi(location),
+            return_exceptions=True,
+        )
+
+        if isinstance(weather, BaseException):
+            raise weather
+
+        if isinstance(aqi, BaseException):
+            aqi = None
+
+    cache.save(location, weather, aqi, query)
+
+    response = WeatherResponse(location, weather, aqi)
+
+    if json_output:
+        print(msgspec.json.encode(response).decode())
+
+        return
+
+    render_weather(response, theme, days)
+
+
+async def run_setup() -> None:
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        location, unit_system = await onboarding(
+            GeolocationService(client), GeocodingService(client, cache)
+        )
+        config.save(location, unit_system)