kiahk 0.1.2

Coptic calendar arithmetic — date conversion, Easter, and feast days

kiahk (Python)

Coptic calendar arithmetic — date conversion, Easter, and feast days. Python port of kiahk. Identical results to all other ports against core/test-vectors.json.

Install

pip install kiahk

Or from this repo for development:

cd py
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Quick start

from kiahk import CopticDate, GregorianDate, CopticCalendar

# Convert Gregorian → Coptic
g = GregorianDate(2025, 1, 11)
c = g.to_coptic()
print(c.year, c.month, c.day)  # 1741 5 3

# Convert Coptic → Gregorian
c2 = CopticDate(1742, 1, 1)
g2 = c2.to_gregorian()
print(g2.year, g2.month, g2.day)  # 2025 9 11

# Coptic Easter for a Gregorian year
easter = CopticCalendar.easter_date(2025)
print(easter.year, easter.month, easter.day)  # 2025 4 20

# All major feasts for a Gregorian year, sorted by date
for feast in CopticCalendar.year_feasts(2025):
    g = feast.gregorian_date
    print(f"{g.year}-{g.month:02d}-{g.day:02d}  {feast.name('en')}")

Sample output:

1741 5 3
2025 9 11
2025 4 20
2025-01-07  Nativity of Christ
2025-01-19  Epiphany (Theophany)
2025-02-10  Nineveh Fast
2025-02-24  Great Lent (start)
2025-04-07  Annunciation
2025-04-13  Palm Sunday
2025-04-20  Easter Sunday
2025-05-29  Ascension
2025-06-08  Pentecost
2025-08-22  Assumption of Mary
2025-09-27  Feast of the Cross

Render a date in English and Arabic

The library exposes Coptic month names in en + ar via CopticCalendar.month_name(month, locale). The full 13-entry table is also re-exported as COPTIC_MONTHS for callers that prefer raw data.

from kiahk import GregorianDate, CopticCalendar

g = GregorianDate(2025, 4, 20)
c = g.to_coptic()
print(f"{c.day} {CopticCalendar.month_name(c.month, 'en')} {c.year} AM")
print(f"{c.day} {CopticCalendar.month_name(c.month, 'ar')} {c.year} للشهداء")

Sample output:

12 Parmouti 1741 AM
12 برمودة 1741 للشهداء

API at a glance

Type / method	Purpose
GregorianDate(y, m, d)	Value type; raises InvalidGregorianDateError on bad input
GregorianDate.to_coptic() → CopticDate	Convert
GregorianDate.to_native_date() / from_native_date(date)	Interop with datetime.date
CopticDate(y, m, d)	Value type; raises InvalidCopticDateError on bad input
CopticDate.to_gregorian() → GregorianDate	Convert
Feast	id, type, category, gregorian_date, .name(locale)
Feast.name("fr")	Raises UnsupportedLocaleError for unknown locale
CopticCalendar.easter_date(year) → GregorianDate	Coptic Easter
CopticCalendar.moveable_feast(feast_id, year) → Feast	One moveable feast
CopticCalendar.year_feasts(year) → list[Feast]	All feasts, sorted ascending
CopticCalendar.month_name(month, locale) → str	Coptic month name; raises InvalidCopticMonthError / UnsupportedLocaleError
COPTIC_MONTHS	13-entry list of dicts (mirrors core/coptic_months.json)

Supported locales for Feast.name(...) and CopticCalendar.month_name(...): en, ar.

Run tests

cd py
.venv/bin/pytest -v

License

Licensed under the MIT License.

Maintained by Amir Magdy at WizardLabz.