PlanetaryTime/PROJECT.md

# PROJECT.md

## Project Overview

**PlanetaryTime** is a Python library for representing and working with time on other bodies in the Solar System, similar in spirit to the standard `datetime` module.

---

## Core Concept

Time on a given planetary body is expressed using a human-readable clock where **the hour is preserved as close to one Earth hour as possible**.

The number of hours in a planetary day is derived from the length of that body's sidereal rotation period expressed in Earth hours, rounded to the nearest integer:

```
hours_per_day = round(rotation_period_in_earth_hours)
```

Example: if a body rotates once every 24.6 Earth hours, its day has 25 hours, each approximately 1 Earth hour long.

---

## Epoch

The starting point for counting days (sol 0 / day 0) is configurable per body and per use case:

- **Discovery epoch** — the date the body was officially discovered
- **Contact epoch** — the date of first contact with the body:
  - landing of an automated probe, or
  - landing of a crewed mission

The epoch is set when constructing a planetary time object and determines what "day 1" means.

---

## Planned Public API

```python
from planetarytime import PlanetaryTime, Body, Epoch

# construct from Earth datetime + target body + epoch choice
pt = PlanetaryTime.from_earth(datetime.utcnow(), body=Body.MARS, epoch=Epoch.DISCOVERY)

pt.day          # integer day number since epoch
pt.hour         # hour within the current day (0-indexed)
pt.minute       # minute within the current hour
pt.second       # second within the current minute
pt.body         # the planetary body
pt.epoch        # the epoch in use

str(pt)         # human-readable: e.g. "Sol 142, 09:35:22 (Mars / Discovery epoch)"
```

---

## Supported Bodies

Initial target: planets and major bodies of the Solar System with known rotation periods.

| Body    | Rotation period (Earth h) | Hours per day |
|---------|--------------------------|---------------|
| Mercury | 1407.6                   | 1408          |
| Venus   | 5832.5 (retrograde)      | 5833          |
| Mars    | 24.6                     | 25            |
| Jupiter | 9.9                      | 10            |
| Saturn  | 10.7                     | 11            |
| Uranus  | 17.2                     | 17            |
| Neptune | 16.1                     | 16            |

Moon and dwarf planets (Pluto, Ceres, Eris) may be added later.

---

## Current State

- Project scaffolded (Poetry, src layout, tests directory)
- No implementation yet

## Pending work

- TODO: Define `Body` enum with rotation periods
- TODO: Define `Epoch` enum and epoch registry
- TODO: Implement core `PlanetaryTime` class
- TODO: Implement conversion from Earth `datetime`
- TODO: Implement `__str__` / `__repr__`
- TODO: Implement `scripts/refresh_data.py` — fetches rotation periods, orbital periods and discovery dates from Wikidata SPARQL endpoint and regenerates hardcoded data in `body.py`, `moon.py` and `epoch.py`; script is not part of the distributed package