moontime 0.3.3

Temporal Moon timekeeping

MoonTime Staging

This folder is a temporary staging area to branch MoonTime into its own repository. It is intentionally ignored by Git (see repo .gitignore) so we can iterate locally without affecting the main repo until the extraction is complete.

Plan

• Extract MoonTime class and helpers from mooncal.py into a standalone package.
• Preserve public API: MoonTime, moontime(), temporal_hms(), display_str, add_temporal(), temporal_seconds_to(), plus isoformat() and MoonTime.fromisoformat().
• Keep lunar fields available: lunar_year, lunar_month_index, lunar_month_name, lunar_day, lunar_weekday, lunar_sun_sign, moon_phase.
• Use AetherField at runtime for lunar_sun_sign (no Skyfield at runtime).
• Decouple from mooncal: use internal moontime.ledger and moontime.aether wrappers.

Seasonal + Sunrise Features (Aether-backed)

• MoonTime now exposes:
  • season: "Spring" | "Summer" | "Autumn" | "Winter" (North default; set MOONTIME_HEMISPHERE=S for Southern)
  • season_start: most recent equinox/solstice boundary timestamp
  • day_length_seconds, day_length_delta_seconds, day_length_trend: daylight metrics
  • sunrise_azimuth_deg: degrees from North, clockwise
• sunrise_solstice_scale_0_100: 0≈equinox, 100≈solstice (latitude-aware)
• solar_movement: "north" | "south" | "stationary"
• Temporal strings:
  • lunar_temporal_hms() → L↑ HH:MM:SS / L↓ HH:MM:SS
  • planetary_temporal_hms(body) → e.g., Ju↓ 02:34:10 (Sun..Saturn)
• CLI prints seasonal_summary: {scale} {season} {movement} {trend} after the display line.

Local Layout (staging)

• src/moontime/ — package source (to be populated during extraction)
• tests/ — focused tests for time arithmetic and serialization
• requirements.txt — runtime deps for MoonTime package
• requirements-dev.txt — test-only deps (pytest)

Notes

• This staging area is not committed. When stable, we’ll move it to a new repo and wire CI there.
• Runtime ephemeris: AetherField drives phases/signs. Sunrise/sunset for temporal hours are computed via the host project's skyfieldcomm.twilight helper (no direct Skyfield dependency here). In a fully standalone repo, provide a light twilight utility or persist sunrise in the ledger.

Dev Tips

• Create a venv: python -m venv venv && .\\venv\\Scripts\\activate
• Install deps: pip install -r requirements.txt
• Install test deps: pip install -r requirements-dev.txt
• Run only MoonTime tests: pytest -q moontime/tests
• If pytest is missing, install it: pip install pytest

Config

• MOONTIME_TZ: default timezone (IANA string), default UTC.
• MOONTIME_COORDS: default coordinates "lat,lon", default "0,0".
• MOONTIME_HEMISPHERE: default N; set S to invert seasonal naming.
• Ledger sources: prefers in-memory serapeum.all_lunar_years; falls back to all_lunar_years.json at repo root or calendars/all_lunar_years.json.
• MOONTIME_SUN_PROVIDER: choose sunrise/sunset provider: auto (default; AetherField then twilight), aether (AetherField only, falls back to twilight if error), or twilight (use host skyfieldcomm.twilight).

Future Extraction

• AetherField: moontime.aether wraps the host aetherfield. For a standalone repo, either vendor the calibrated model or declare it as an optional dependency and add a small loader.