format-time-engine 1.0.1

A modular time and calendar engine with customizable ticks, sun/moon altitude tables, and dynamic parameter propagation.

A battle-tested, headless time & calendar engine for games, simulations, automation—and anything else that needs a clock.

---

Problem 

Projects that simulate a world—whether it’s a game, a physics engine, a climate model, or an automation pipeline—inevitably need:

• A reliable clock with a reliable calendar to back it
• Accurate celestial data (sunrise/sunset, moon phases, altitudes)
• Event hooks so subsystems can react to time-changes
• Robust rollover logic and edge-case handling

Rolling your own solution is error-prone, time-consuming, and quickly becomes a maintenance nightmare as your project grows.

---

Solution 

format_time turns “build-an-engine-from-scratch” into “install-and-go.” It provides:

• 🎲 Modular Core

  • Pure-Python Time class: .advance(ticks), .current_datetime()
  • Fully configurable calendar units (ticks/hr, hrs/day, days/month, months/yr)

• 🌙 Sun & Moon Tables

  • Precomputed NumPy arrays for fast altitude lookups
  • Automatic rebuilds when you tweak calendar parameters

• ♻️ Dynamic Parameters

  • ParametersManager backed by SQLite
  • Change any parameter at runtime—everything updates instantly

• 🔔 Event Notifications

  • UDP-broadcast on every tick advance
  • Easy listeners for UIs, game loops, analytics pipelines

• ✅ Production-Quality

  • 112 tests (unit, edge-case, integration, module)
  • Black / isort / flake8 pre-commit hooks
  • Python 3.12+ support, MIT license

---

Installation 

# Core engine only
pip install format_time_engine

# GIS / astronomy extras (sun & moon tables)
pip install format_time_engine[geo]

# Qt & matplotlib for custom UIs
pip install format_time_engine[ui]

# Everything
pip install format_time_engine[geo,ui]

---

Quickstart 

from time_engine.unified_time_module import UnifiedTimeModule
utm = UnifiedTimeModule(data_dir="calendar_data")

# Advance by 3,600 ticks
utm.time.advance(3600)

# Read current datetime
dt = utm.time.current_datetime()
print(
  f"{dt['year']}-{dt['month']:02}-{dt['day']:02} "
  f"{dt['hour']:02}:{dt['tick']}/{utm.time.ticks_per_hour} ticks"
)

# Query sun altitude
sun_alt = utm.sun_api().get_altitude()
print(f"Sun altitude: {sun_alt:.1f}°")

---

Configuration 

All core parameters live in a SQLite database (parameters.db). Change them on the fly:

from parameters.manager import ParametersManager

pm = ParametersManager()
pm.set("time", "hours_per_day", "30")
# calendars and notifications rebuild automatically

Override the DB path:

export PARAM_DB_PATH=/path/to/my_params.db

---

Contributing 

1. Fork & clone

   git clone [e-mail]:ProphetGang/format_time.git
   cd format_time
   

2. Install dev tools

   pip install -e .[dev]
   pre-commit install
   pre-commit run --all-files
   pytest
   

---

License 

This project is MIT-licensed. See LICENSE for details.