Metadata-Version: 2.4
Name: py-weatherspect
Version: 0.0.2
Summary: Python port of WeatherSpect, an ASCII weather animation
Project-URL: Original WeatherSpect, https://robobunny.com/projects/weatherspect/html/
Project-URL: Py-Weatherspect auf Sourceforge, https://sourceforge.net/p/py-weatherspect
Author-email: Ulrich Schwenk <ulrich.schwenk@gmail.com>
License: GPL-2.0-or-later
License-File: LICENSE
Keywords: animation,ascii,cli,ncurses,terminal,weather
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Requires-Dist: blessed
Requires-Dist: click
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: black[d]; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: poethepoet; extra == 'dev'
Requires-Dist: pyinstaller; extra == 'dev'
Requires-Dist: pylint; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# py-weatherspect

**py-weatherspect** is a Python port of [WeatherSpect](https://robobunny.com/projects/weatherspect/html/),
the ASCII weather animation originally written by Kirk Baucom.

> WeatherSpect provides a reasonably accurate simulation of what the weather
> looks like outside, in ASCII art. It includes rain, snow, lightning, sleet,
> and hail. The windspeed and cloudiness are reflected in the velocity and
> quantity of clouds. There are trees that age, reproduce and die over the
> course of an hour, and a sun and moon that follow the actual sunrise and
> moonrise. There's also a dancing turtle.

```
     .---.             ___     *    .  *  .   *
    /  O  \          /\___\  *   .       .
   | o     |  .---.  \_____\         *        .
    \  o O/  /  * .\  _____ .  *        .
     '---'   | *  . |/  . * \     *  .      *
   ~~~~~~~~~~'-----'~~~~~~~~~~~~~~~~~~~~~~~~~~
```

## Features

- Live weather data via **OpenWeatherMap** or **Open-Meteo**
- Rain, snow, sleet, hail, fog, thunder and lightning
- Wind-speed-dependent cloud movement and density
- Sun and moon following actual rise/set times with moon phases
- Seasonal entities: 🎃 Ghost (Halloween), 🦃 Turkey (Thanksgiving), 🎅 Santa (Christmas)
- 20+ animated critters: Mario, Pac-Man, rocket, helicopter, ducks, elephant, turtle, …
- Day/night sky colour (cyan by day, dark blue by night)
- Interactive override menu (`o`) to change weather, time-of-day, and moon phase live
- Color terminal support via [blessed](https://pypi.org/project/blessed/)

## Installation

```bash
pip install py-weatherspect
```

Requires Python 3.10+ and a color-capable terminal (xterm-256color recommended).

## Quick Start

### 1. Create a config file

```bash
py-weatherspect --create-config
```

You will be prompted for your location (city, ZIP code, "City, Country", etc.).
The config is saved to `~/.weatherspect`.

### 2. Run the animation

```bash
py-weatherspect
```

Press `q` or `Esc` to quit.

### All options

```
py-weatherspect [OPTIONS]

  -f, --config-file TEXT   Path to config file (default: ~/.weatherspect)
  -c, --create-config      Create a new config file interactively, then exit
  --width INTEGER          Terminal width  [default: 80]
  --height INTEGER         Terminal height [default: 24]
  --no-color               Disable color output
  --frames INTEGER         Stop after N frames (useful for scripting/tests)
  --help                   Show this message and exit
```

### Static renderer (no animation, single frame to stdout)

```bash
py-weatherspect-static-render [OPTIONS]
```

## Runtime Keys

| Key | Action |
|-----|--------|
| `q` / `Esc` | Quit |
| `h` | Toggle help overlay |
| `w` | Toggle weather info overlay |
| `d` | Toggle debug overlay |
| `u` | Force weather data update |
| `r` | Redraw — remove all entities and recreate them |
| `p` | Pause / unpause animation |
| `o` | Toggle override menu (change weather, time, moon phase, spawn entities) |

### Override menu (`o`)

While the override menu is open:

| Key | Action |
|-----|--------|
| `1`–`9` | Switch to a weather scenario (clear, rain, snow, thunder, …) |
| `0` | Return to live weather data |
| `+` / `-` | Advance / rewind simulated time by 1 hour |
| `z` | Reset time to real clock |
| `M` | Cycle moon phase |
| `a`–`z` | Spawn a random entity (shown in the menu) |

## Configuration

The config file (`~/.weatherspect`) is a simple key=value format:

```ini
location      = Berlin, Germany
retr_interval = 30          # weather update interval in minutes
tree_lifespan = 60          # minutes a tree lives before dying
frame_delay   = 0.08        # seconds between animation frames
display_units = metric      # metric or imperial
color         = 1           # 1 = color, 0 = monochrome
entities      = 5           # number of random entities on screen
```

## Weather Providers

By default **OpenWeatherMap** is used. A free API key is not required for
the current location-based lookup, but rate limits apply. Alternatively the
**Open-Meteo** provider (no API key needed) is available; switching providers
is a configuration option in future releases.

## Development

```bash
git clone ...
cd py-weatherspect
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'

# Run tests
python -m unittest discover

# Run parity snapshots against the Perl baseline
poe parity-snapshots

# Build distribution
poe build
```

## Credits

- **Kirk Baucom** `<kbaucom@schizoid.com>` — original WeatherSpect and Term::Animation (Perl)
- **Kevin Ferree** — ASCII art (marked `kf` in source)
- **Hayley Wakenshaw** — ASCII art (marked `hjw` in source)
- **Joan Stark** — ASCII art (marked `jgs` in source)
- **Ulrich Schwenk** `<ulrich.schwenk@gmail.com>` — Python port

Full provenance and license notes: [`doc/credits.md`](doc/credits.md)

## License

GNU General Public License v2 or later (GPL-2.0-or-later).
See [`LICENSE`](LICENSE) for the full text.
