py-weatherspect 0.0.2

Python port of WeatherSpect, an ASCII weather animation

py-weatherspect

py-weatherspect is a Python port of WeatherSpect, 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

Installation

pip install py-weatherspect

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

Quick Start

1. Create a config file

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

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)

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:

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

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 <[e-mail]> — 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 <[e-mail]> — Python port

Full provenance and license notes: doc/credits.md

License

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