Metadata-Version: 2.4
Name: weatherz
Version: 0.0.1
Summary: Deterministic weather generation for games and simulations
Author-email: "Imran Bin Gifary (System Delta or Imran Delta Online)" <imran.sdelta@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/Imran-Delta/weather
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# weather
A deterministic weather generation library for games and simulations.
Given a single time input (and optional location/climate parameters), it returns a complete, reproducible weather report.
Features
 * Fully deterministic: Same input always yields the same output.
 * Flexible Time: Supports game minutes, real-time, or current UTC.
 * Geographic Context: Optional latitude, longitude, and elevation for fine-tuning.
 * Climate Profiles: Built-in Köppen climate profiles (extensible).
 * Comprehensive Data:
   * Temperature, pressure, humidity, dew point, wind (speed/direction/cardinal).
   * Precipitation probability, cloud cover, instability (CAPE-like).
   * 20+ weather conditions (clear, rain, snow, thunderstorm, blizzard, etc.).
   * Special atmospheric phenomena: aurora, rainbow, sun dog, halo.
   * Moon phase (with year drift) and seasonal events (equinoxes/solstices).
   * Flavor text and ASCII art for every condition.
 * Customizable: All disasters can be enabled/disabled per profile.
 * NEW: Per-trend memory isolation – pass a trend_id to keep smoothing separate for concurrent use.
 * NEW: WeatherArchive – persistent SQLite storage of sparse checkpoints, ensuring smooth weather even when jumping to arbitrary times.
Installation
Copy weather.py into your project and import:
from weather import weather, WeatherData, list_koppen_codes, WeatherArchive

(No external dependencies – only the Python standard library.)
Usage
Basic – current weather at default location
w = weather()
print(f"{w.condition} at {w.temperature}°C")
print(w.ascii_art)
print(w.flavor)

Advanced Time & Location
### Specify game minutes
w = weather(game_minutes=123456)

### Use real time (UTC)
from datetime import datetime
w = weather(real_time=datetime(2025, 6, 1, 12, 0))

### Scale time (e.g., 1 real minute = 12 game minutes)
w = weather(real_time=datetime.now(), real_time_scale=12)

### Set location (latitude affects aurora; elevation applies lapse rate)
w = weather(latitude=60.0, elevation=200, koppen="Dfd")

### Isolate smoothing per trend
w1 = weather(game_minutes=1000, trend_id="siberia")
w2 = weather(game_minutes=1000, trend_id="desert")   ### separate memory

WeatherArchive – Persistent, Smooth Trends
The WeatherArchive class stores weather checkpoints in a local SQLite database. When you request a time, it generates forward from the nearest checkpoint, ensuring smooth transitions without storing every minute.
archive = WeatherArchive("my_weather.db")

### Add a trend (location + climate)
trend_id = archive.add_trend(
    name="Siberian Outpost",
    latitude=60.0,
    longitude=120.0,
    elevation=200.0,
    koppen="Dfd"
)

### Get weather at game minute 5000 
w = archive.get_weather(trend_id, 5000)

### Later, get minute 6000 (uses checkpoint at 5000)
w2 = archive.get_weather(trend_id, 6000)

### Read‑only mode (no new checkpoints saved)
w3 = archive.get_weather(trend_id, 7000, read_only=True)

> Thread Safety: WeatherArchive is thread-safe. Concurrent requests for different trends run in parallel; requests for the same trend are serialized to preserve smoothing logic.
> 
WeatherData Fields
| Field | Type | Description |
|---|---|---|
| game_minutes | int | Internal game minute count |
| datetime_str | str | Formatted "Year X, Day Y, HH:MM" |
| temperature | float | Air temperature (°C) |
| feels_like | float | Apparent temperature (°C) |
| pressure | float | Atmospheric pressure (hPa) |
| humidity | float | Relative humidity (%) |
| dew_point | float | Dew point (°C) |
| wind_speed | float | Wind speed (m/s) |
| wind_direction | float | Wind direction (degrees) |
| wind_cardinal | str | Cardinal direction (N, NNE, etc.) |
| condition | str | Weather condition (e.g., "light rain") |
| cloud_cover | int | Cloud cover (%) |
| precipitation_prob | float | Precipitation probability (%) |
| instability | float | CAPE‑like instability (J/kg) |
| moon_phase | str | Moon phase name |
| moon_emoji | str | Moon phase emoji |
| season_event | str/None | Solstice/equinox if within ±2 days |
| flavor | str | Descriptive flavor text |
| ascii_art | str | ASCII art representing the condition |

### `- Update LOGS -`

# -Update 0.0.1-
 * Basically added a way to ensure smoothness and do that even if multiple functions sre calling weather history function.
 * Added trend_id parameter to weather() for isolated smoothing memory.
 * Added WeatherArchive class for persistent, checkpoint-based storage.
 * Thread-safe archive with per-trend locks.

# -Update 0.0.1dev1-
* Bro, this is 0.0.1. Why you even looking here?
