Initial commit

PROJECT.md

@@ -0,0 +1,88 @@
+# 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
+
+## TODO
+
+- Define `Body` enum with rotation periods
+- Define `Epoch` enum and epoch registry
+- Implement core `PlanetaryTime` class
+- Implement conversion from Earth `datetime`
+- Implement `__str__` / `__repr__`
+- Write tests for conversion accuracy
+- Write tests for epoch switching
+- Populate README with usage examples