wevva 0.1.0__tar.gz

wevva-0.1.0/.gitignore

@@ -0,0 +1,178 @@
+dist
+.venv
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+__pycache__
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

wevva-0.1.0/LICENSE

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

wevva-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: wevva
+Version: 0.1.0
+Summary: Textual TUI for viewing weather via Open-Meteo
+Author-email: Nick Ferguson <nick.ferguson@ed.ac.uk>
+License: MIT License
+        
+        Copyright (c) 2026 Nick Ferguson
+        
+        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.
+License-File: LICENSE
+Keywords: open-meteo,terminal,textual,tui,weather
+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 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pycountry>=24.6.1
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: textual>=3.1.0
+Requires-Dist: typer>=0.21.1
+Requires-Dist: wcwidth>=0.2.13
+Description-Content-Type: text/markdown
+
+# wevva
+
+`wevva` is a weather TUI built with [Textual](https://textual.textualize.io/) and powered by [Open-Meteo](https://open-meteo.com/).
+
+<p align="center">
+  <img src="docs/assets/wevva-main.png" alt="wevva weather TUI screenshot" width="900">
+</p>
+
+## Highlights
+
+- Place search using Open-Meteo geocoding
+- Current, hourly, and daily forecasts with detailed weather parameters and keyboard navigation
+- Unit preferences (temperature, wind, precipitation)
+- Theme and emoji toggles
+- Interactive setup wizard for defaults
+- Reusable Python API (async + sync helpers)
+
+## Quick Start
+
+First, install [uv](https://docs.astral.sh/uv/):
+
+```bash
+curl -Ls https://astral.sh/uv/install.sh | sh
+```
+
+Then, using `uvx`, run `wevva`:
+
+```bash
+uvx wevva
+```
+
+to launch the app without cloning the repo. This will install `wevva` as a package in a temporary environment and run it from there.
+
+Alternatively, you can clone the repo and run from the local source:
+
+```bash
+uvx --from . wevva
+```
+
+Requires Python `>=3.12`.
+
+## First-Time Setup
+
+Run the setup wizard to save defaults:
+
+```bash
+uvx wevva setup
+```
+
+Save settings without launching:
+
+```bash
+uvx wevva setup --no-launch
+```
+
+## Useful Commands
+
+```bash
+# Start normally (uses saved defaults)
+uvx wevva
+
+# Start directly at a location
+uvx wevva --location "Edinburgh"
+
+# One-run overrides
+uvx wevva --theme dracula --no-emoji
+uvx wevva --temperature-unit fahrenheit --wind-speed-unit mph
+
+# Manage saved default location
+uvx wevva --set-default-location "New York"
+uvx wevva --clear-default-location
+```
+
+## Library Usage
+
+This library is designed to be used as a TUI, but I have also exposed a minimal set of functions for fetching weather data and geocoding that can be used in other Python contexts. These are available as both async and sync versions, depending on your needs.
+
+Install as a package:
+
+```bash
+uv add wevva
+```
+
+Simple sync usage (nice for scripts):
+
+```python
+from wevva import forecast_by_place_sync
+
+bundle = forecast_by_place_sync("Edinburgh")
+print(bundle.metadata.name, bundle.metadata.country)
+print(bundle.current.get_temperature(), bundle.current.forecast_units.get("temperature_2m"))
+```
+
+Async usage (best for apps/services):
+
+```python
+import asyncio
+from wevva import forecast_by_coordinates
+
+async def main() -> None:
+    bundle = await forecast_by_coordinates(lat=55.9533, lon=-3.1883)
+    print(bundle.daily.get_temperature_max(0))
+    print(bundle.hourly.get_condition_abbreviation(0))
+
+asyncio.run(main())
+```
+
+You can also geocode from Python:
+
+```python
+from wevva import geocode_sync
+
+matches = geocode_sync("Glasgow", count=3)
+for match in matches:
+    print(match.name, match.country, match.latitude, match.longitude)
+```
+
+## In-App Keys
+
+- `s` search for place
+- `r` refresh weather
+- `u` open unit settings
+- `h` or `?` open help
+- `c` credits
+- `q` quit
+
+## Config
+
+Preferences are stored at:
+
+```text
+~/.config/wevva/config.json
+```
+
+Saved settings include:
+- units
+- theme
+- emoji preference
+- default location (and cached resolved location metadata)
+
+## Notes
+
+- Emoji rendering support varies by terminal/font/locale.
+- TUI is the primary focus, but a lightweight Python API is now exported too.
+
+## Known Issues
+
+- Layout not super flexible, requires a terminal size of at least 100x43 for all elements to show fully.
+- Temperature colour scaling is using the Met Office scale, the colours of which may not play nicely with all themes as they get towards the more extreme ends of the scale.

wevva-0.1.0/README.md

@@ -0,0 +1,149 @@
+# wevva
+
+`wevva` is a weather TUI built with [Textual](https://textual.textualize.io/) and powered by [Open-Meteo](https://open-meteo.com/).
+
+<p align="center">
+  <img src="docs/assets/wevva-main.png" alt="wevva weather TUI screenshot" width="900">
+</p>
+
+## Highlights
+
+- Place search using Open-Meteo geocoding
+- Current, hourly, and daily forecasts with detailed weather parameters and keyboard navigation
+- Unit preferences (temperature, wind, precipitation)
+- Theme and emoji toggles
+- Interactive setup wizard for defaults
+- Reusable Python API (async + sync helpers)
+
+## Quick Start
+
+First, install [uv](https://docs.astral.sh/uv/):
+
+```bash
+curl -Ls https://astral.sh/uv/install.sh | sh
+```
+
+Then, using `uvx`, run `wevva`:
+
+```bash
+uvx wevva
+```
+
+to launch the app without cloning the repo. This will install `wevva` as a package in a temporary environment and run it from there.
+
+Alternatively, you can clone the repo and run from the local source:
+
+```bash
+uvx --from . wevva
+```
+
+Requires Python `>=3.12`.
+
+## First-Time Setup
+
+Run the setup wizard to save defaults:
+
+```bash
+uvx wevva setup
+```
+
+Save settings without launching:
+
+```bash
+uvx wevva setup --no-launch
+```
+
+## Useful Commands
+
+```bash
+# Start normally (uses saved defaults)
+uvx wevva
+
+# Start directly at a location
+uvx wevva --location "Edinburgh"
+
+# One-run overrides
+uvx wevva --theme dracula --no-emoji
+uvx wevva --temperature-unit fahrenheit --wind-speed-unit mph
+
+# Manage saved default location
+uvx wevva --set-default-location "New York"
+uvx wevva --clear-default-location
+```
+
+## Library Usage
+
+This library is designed to be used as a TUI, but I have also exposed a minimal set of functions for fetching weather data and geocoding that can be used in other Python contexts. These are available as both async and sync versions, depending on your needs.
+
+Install as a package:
+
+```bash
+uv add wevva
+```
+
+Simple sync usage (nice for scripts):
+
+```python
+from wevva import forecast_by_place_sync
+
+bundle = forecast_by_place_sync("Edinburgh")
+print(bundle.metadata.name, bundle.metadata.country)
+print(bundle.current.get_temperature(), bundle.current.forecast_units.get("temperature_2m"))
+```
+
+Async usage (best for apps/services):
+
+```python
+import asyncio
+from wevva import forecast_by_coordinates
+
+async def main() -> None:
+    bundle = await forecast_by_coordinates(lat=55.9533, lon=-3.1883)
+    print(bundle.daily.get_temperature_max(0))
+    print(bundle.hourly.get_condition_abbreviation(0))
+
+asyncio.run(main())
+```
+
+You can also geocode from Python:
+
+```python
+from wevva import geocode_sync
+
+matches = geocode_sync("Glasgow", count=3)
+for match in matches:
+    print(match.name, match.country, match.latitude, match.longitude)
+```
+
+## In-App Keys
+
+- `s` search for place
+- `r` refresh weather
+- `u` open unit settings
+- `h` or `?` open help
+- `c` credits
+- `q` quit
+
+## Config
+
+Preferences are stored at:
+
+```text
+~/.config/wevva/config.json
+```
+
+Saved settings include:
+- units
+- theme
+- emoji preference
+- default location (and cached resolved location metadata)
+
+## Notes
+
+- Emoji rendering support varies by terminal/font/locale.
+- TUI is the primary focus, but a lightweight Python API is now exported too.
+
+## Known Issues
+
+- Layout not super flexible, requires a terminal size of at least 100x43 for all elements to show fully.
+- Temperature colour scaling is using the Met Office scale, the colours of which may not play nicely with all themes as they get towards the more extreme ends of the scale.

wevva-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "wevva"
+version = "0.1.0"
+description = "Textual TUI for viewing weather via Open-Meteo"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+authors = [ { name = "Nick Ferguson", email = "nick.ferguson@ed.ac.uk" } ]
+keywords = ["textual", "tui", "weather", "open-meteo", "terminal"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+    "Topic :: Terminals",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pycountry>=24.6.1",
+    "questionary>=2.1.1",
+    "textual>=3.1.0",
+    "typer>=0.21.1",
+    "wcwidth>=0.2.13",
+]
+
+[project.scripts]
+wevva = "wevva.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["wevva"]
+
+[tool.hatch.build.targets.sdist]
+include = ["wevva/**", "README.md", "LICENSE", "pyproject.toml"]

wevva-0.1.0/wevva/__init__.py

@@ -0,0 +1,50 @@
+"""Wevva package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from wevva.api import (
+    LocationNotFoundError,
+    WevvaAPIError,
+    forecast_by_coordinates,
+    forecast_by_coordinates_sync,
+    forecast_by_place,
+    forecast_by_place_sync,
+    geocode,
+    geocode_sync,
+)
+from wevva.location_metadata import LocationMetadata
+from wevva.models import ForecastBundle
+from wevva.openmeteo import (
+    CurrentOpenMeteoForecast,
+    DailyOpenMeteoForecast,
+    HourlyOpenMeteoForecast,
+)
+
+CurrentForecast = CurrentOpenMeteoForecast
+HourlyForecast = HourlyOpenMeteoForecast
+DailyForecast = DailyOpenMeteoForecast
+
+__all__ = [
+    "CurrentForecast",
+    "CurrentOpenMeteoForecast",
+    "DailyForecast",
+    "DailyOpenMeteoForecast",
+    "ForecastBundle",
+    "HourlyForecast",
+    "HourlyOpenMeteoForecast",
+    "LocationMetadata",
+    "LocationNotFoundError",
+    "WevvaAPIError",
+    "__version__",
+    "forecast_by_coordinates",
+    "forecast_by_coordinates_sync",
+    "forecast_by_place",
+    "forecast_by_place_sync",
+    "geocode",
+    "geocode_sync",
+]
+
+try:
+    __version__ = version("wevva")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

wevva-0.1.0/wevva/__main__.py

@@ -0,0 +1,11 @@
+"""Run Wevva via `python -m wevva`."""
+
+from wevva.cli import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()