moontime 0.4.9

Temporal Moon timekeeping

MoonTime

MoonTime is a temporal system designed to translate human time into something older, quieter, and a little less linear.

It began with a simple problem:

If someone says “by the next moon”… how long is that, exactly?

MoonTime answers that by mapping any moment into a lunar-aware calendar, where phases, cycles, and celestial relationships shape the flow of time.

---

🌙 Features

• 🌗 Real-time lunar phase and illumination

• 🌌 Continuous lunar calendar (year, month, day)

• 🧭 Seasonal awareness

• 🕰️ Human-readable + machine-friendly formatting

• 🔁 Conversion from:

  • datetime
  • CLI input

• 🖥️ Command-line interface with planetary time modes

---

📦 Installation

pip install moontime

---

🚀 Quick Example

from moontime import MoonTime as mt

def example():

    moon = mt.now()  # Pull this moment 

    # Basic data on the moment:
    print("Readout", moon)
    print("Season:", moon.season)
    print("Moon Phase:", moon.phase)
    print("Moon illumination:", moon.illumination)
    print("Moon angle:", moon.angle)
    print("Lunar year:", moon.year)
    print("Lunar month:", moon.month)
    print("Lunar day:", moon.day)
    print("Name of the month:", moon.lunar_month_name)
    print("Day of the week:", moon.lunar_weekday)

    # Functions:
    if moon.is_day:
        print("Is day:", "true")
    else:
        print("Is day:", "false")

    print("strftime:", moon.strftime('%Y%m%d%H%M%S'))


if __name__ == "__main__":
    example()

Example Output

Readout 6739-02-05 10:52:54.724282
Season: Spring
Moon Phase: First Quarter
Moon illumination: 42
Moon angle: 81.2754265988915
Lunar year: 6739
Lunar month: 2
Lunar day: 5
Name of the month: Umbra
Day of the week: Nycturia
Is day: false
strftime: 67390205105254

---

🧭 Core Concepts

MoonTime Object

moon = mt.now()

Represents a single moment translated into the MoonTime system.

---

Lunar Calendar

Each moment includes:

• Year → Continuous count (not tied to Gregorian)
• Month → Lunar cycle index
• Day → Position within the cycle
• Month Name → Symbolic naming (e.g. Umbra)
• Weekday → Custom lunar week system

---

Phase & Illumination

moon.phase
moon.illumination

• Phase: textual description (e.g. First Quarter)
• Illumination: percentage of visible moon

---

Angle

moon.angle

Angular relationship between the Moon and the Sun.

This is the underlying value that determines phase.

---

Day / Night

moon.is_day

Boolean indicating whether the sun is above the horizon.

---

Formatting

moon.strftime('%Y%m%d%H%M%S')

Works similarly to standard datetime.strftime, but uses MoonTime values.

---

⏳ Conversions

From datetime

from datetime import datetime, timezone

mt.from_datetime(datetime.now(timezone.utc))

Current Moment

mt.now()

---

🖥️ CLI Usage

MoonTime includes a command-line interface for quick queries.

Current Time

moontime now

6739-02-05 10:41:06.718833

---

Specific Date

moontime at 2025-05-12

6738-02-13 07:23:37.032349

moontime at 2025-05-01T12:34:56

6738-02-02 19:37:30.418148

---

Solar / Planetary Temporal Time Modes

moontime now --sun-time

dYO - 6739-02-05 10:41:51.168

moontime now --mars-time

Ma↓ 04:07:19

moontime now --planet-time moon

L↓ 04:55:46

These modes expose alternative time flows based on planetary cycles.

---

🧬 Design Philosophy

MoonTime is built to be:

• Continuous → No hard resets or calendar discontinuities
• Interoperable → Works alongside standard datetime
• Expressive → Carries meaning beyond raw timestamps
• Deterministic → Same input always yields the same moment

---

🌌 Ecosystem

MoonTime serves as the temporal foundation for:

• aetherfield → planetary positions and alignments
• Other systems that require lunar-aware timing

---

🧪 Status

Early release. Core behavior is stable, but currently the data is extremely geocentric; allow an error margin of ~±12 hours..

---

🕯️ Closing Note

MoonTime does not replace standard time.

It runs alongside it.

A second clock — one that keeps track of cycles instead of seconds, and makes sense of promises like:

“by the next moon.”