Metadata-Version: 2.4
Name: festal-calendar
Version: 0.1.0
Summary: Astronomical, liturgical, and Celtic calendar calculations
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev

# festal-calendar

A pure Python library providing astronomical, liturgical (Church of England),
and Celtic calendar calculations. No I/O, no network, no side effects — a
computation library only.

Used by `sleep-times` and `hymn-choice`.

## Subsystems

- **Astronomical**: solstices, equinoxes, cross-quarter midpoints, and a
  seasonal wake-time calculator
- **Liturgical**: liturgical year boundaries, Easter, all CofE seasons
  (including both Ordinary Times), principal feasts, and saints (filtered by
  region)
- **Celtic**: quarter days and cross-quarter days in both fixed (traditional)
  and astronomical (true midpoint) variants

## Configuration

YAML data files live in `/etc/festal_calendar/`. The package ships defaults
into that directory on install; local edits are preserved on upgrade.

```
/etc/festal_calendar/
    saints.yaml          # saints with feast days, regions, translations
    festivals.yaml       # CofE principal feasts and lesser festivals
    celtic.yaml          # quarter/cross-quarter day names and metadata
    settings.yaml        # tunable defaults (wake time bounds, location, etc.)
```

## APT dependencies

```
python3-yaml
python3-astral
python3-pytz
python3-pytest          # tests only
python3-mypy            # dev only
pycodestyle             # dev only
```

> **Note**: `python3-astral` may require backports on older Debian stable.
> Check `apt-cache show python3-astral` first.

## Installation

```bash
make install
```

This installs the package system-wide and copies default YAML files to
`/etc/festal_calendar/` if they do not already exist (existing files are
never overwritten).

## Development

```bash
make check          # lint + typecheck + tests
make test           # pytest only
make lint           # pycodestyle
make typecheck      # mypy
```

## Usage

```python
from festal_calendar import FestalCalendar
from datetime import date

cal = FestalCalendar(year=2026)

cal.seasons()            # list[Season]
cal.festivals()          # list[Festival]  — all traditions
cal.wake_time(date.today())  # datetime.time
```
