Metadata-Version: 2.4
Name: moontime
Version: 0.4.8
Summary: Temporal Moon timekeeping
Author: WitchMithras
License: Other/Proprietary License
Project-URL: Homepage, https://github.com/WitchMithras/moontime
Keywords: time,calendar,lunar,astronomy,mirror
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytz>=2023.3
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: aetherfield>=0.4.3
Dynamic: license-file

# 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

```bash
pip install moontime
```

---

## 🚀 Quick Example

```python
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

```python
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

```python
moon.phase
moon.illumination
```

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

---

### Angle

```python
moon.angle
```

Angular relationship between the Moon and the Sun.

This is the underlying value that determines phase.

---

### Day / Night

```python
moon.is_day
```

Boolean indicating whether the sun is above the horizon.

---

### Formatting

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

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

---

## ⏳ Conversions

### From `datetime`

```python
from datetime import datetime, timezone

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

### Current Moment

```python
mt.now()
```

---

## 🖥️ CLI Usage

MoonTime includes a command-line interface for quick queries.

### Current Time

```bash
moontime now
```

```
6739-02-05 10:41:06.718833
```

---

### Specific Date

```bash
moontime at 2025-05-12
```

```
6738-02-13 07:23:37.032349
```

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

```
6738-02-02 19:37:30.418148
```

---

### Solar / Planetary Temporal Time Modes

```bash
moontime now --sun-time
```

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

```bash
moontime now --mars-time
```

```
Ma↓ 04:07:19
```

```bash
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.”*
