pyroj 1.2.1

Kurdish solar calendar and conversions (Gregorian, Persian/Jalali, tabular Islamic) using the Python standard library only.

pyroj (Kurdish Calendar)

pyroj is the definitive Python library for the Kurdish solar calendar. It allows for highly accurate date conversions to and from Gregorian, Persian (Jalali), and Tabular Islamic dates.

Built exclusively under the Python standard library, it inherits natively from Python's own datetime ecosystem, serving as a dynamic, robust drop-in replacement for any application. Runtime dependencies: none.

• Python: 3.10+
• Dependency/tool workflow: uv + pyproject.toml
• Supported year range: 1..9999 (aligned with Python datetime.date)

[Research Reference & Calculation Details]
For academics, developers, and researchers seeking the complete historical methodology, epoch derivations, and algorithmic calculations used to yield accurate Kurdish dates, please refer to the detailed Kurdish Date Calculation Research.

Quick Start

KurdishDate and KurdishDateTime inherit natively from python's built-in datetime.date and datetime.datetime. Any standard operation you perform on Python dates can be seamlessly performed on Kurdish dates!

uv pip install pyroj
# or
pip install pyroj

Basic Creation and Conversions

from datetime import date
from pyroj.kurdish import KurdishDate

# 1. Start from a Gregorian Date
d = date(2026, 3, 23)
kd = KurdishDate.from_gregorian(d)

print(kd.year, kd.month, kd.day)  # Output: 2726 1 3

# 2. Or initialize natively in Kurdish
kd_native = KurdishDate(2726, 1, 3)

# 3. Effortless Conversions to other systems
print(kd.to_gregorian())          # Output: 2026-03-23
print(kd.to_persian())            # Output: (1405, 1, 3)
print(kd.to_islamic())            # Output: (1447, 10, 4)

Advanced Date Mathematics

Because pyroj extends standard lib classes natively, you can rely on robust Python implementations for adding/subtracting ranges without worrying about leap years or skipped months!

from datetime import timedelta
from pyroj.kurdish import KurdishDateTime

# Adding 5 days over month boundaries calculates correctly
kd = KurdishDate(2726, 1, 30)
kd_new = kd + timedelta(days=5)

print(kd_new)  # Output: 2726-02-04

# Full Time/Datetime wrappers exist
kdt = KurdishDateTime(2726, 1, 3, hour=15, minute=30, second=0)

kdt_shuffled = kdt - timedelta(hours=36)
print(kdt_shuffled) # Output: 2726-01-02 03:30:00

Beautiful Native Formatting (strftime)

Formatting strings out of the box matches Python's % standard exactly. Furthermore, pyroj natively maps out month and weekday translations depending on your selected locale.

Supported LocaleId dialects include KU (Sorani / Kurdish-Arabic script), AR (Arabic), FA (Persian), TR (Turkish), and EN (English).

from pyroj.kurdish import KurdishDate
from pyroj.locales import LocaleId

kd = KurdishDate(2726, 1, 25)

# Standard English representation
print(kd.strftime("%A, %d %B %Y", locale=LocaleId.EN))
# Output: Tuesday, 25 Xakelêwe 2726

# Sorani execution
print(kd.strftime("%A, %d %B %Y", locale=LocaleId.KU))
# Output: سێشەممە, 25 خاکەلێوە 2726

# Persian representation
print(kd.strftime("%A, %d %B %Y", locale=LocaleId.FA))
# Output: سه‌شنبه, 25 خاکِ‌لِیوَه 2726

# Available formats: 
# %Y (4-digit Year), %y (2-digit Year)
# %B (Full Month), %b (Short Month), %m (2-digit Month), %-m (1-digit Month)
# %A (Full Weekday), %a (Short Weekday), %w (1-7 Index), %-w (1-7 Number)
# %d (2-digit Day), %-d (1-digit Day)
# %H:%M:%S etc. for KurdishDateTime.

Historical Eras

Historically, different subsets of researchers align Year 1 of the Kurdish Calendar differently. pyroj accommodates this dynamically via the KurdishEra Enum:

1. Median Empire Baseline SOLAR_PERSIAN_OFFSET (Default): Evaluates the standard Kurdipedia offset where Kurdish Year = Jalali Year + 1321. (Anchored near 700 BC).
2. Fall of Nineveh Epoch FALL_OF_NINEVEH: Tracks the exact 612 BC battle of Nineveh where Kurdish Year = Jalali Year + 1233.

from pyroj.kurdish import KurdishDate, KurdishEra

# Calculates the year offset depending on standard
kd_nineveh = KurdishDate(2638, 1, 3, era=KurdishEra.FALL_OF_NINEVEH)
print(kd_nineveh.to_gregorian()) # Extrapolates out correctly

Native Tooling (JDN Helpers & Timestamps)

You can convert any Gregorian or Julian representation efficiently down into int / float structs.

from pyroj._core.convert import gregorian_datetime_to_jdn, jdn_to_gregorian_datetime
from pyroj.kurdish import KurdishDate

# Extract absolute Julian Day Number directly
kd = KurdishDate(2726, 1, 1)
print(kd.to_jdn())  # Returns Absolute JDN float

# Restore from JDN
kd_restored = KurdishDate.from_jdn(2461122.5)

Development setup (uv + ruff)

uv sync --extra dev
uv run pytest -q
uv run ruff check pyroj tests
uv run mypy pyroj

Install the package locally for development:

uv pip install -e .

Continuous integration

GitHub Actions runs pytest, ruff, and mypy on Python 3.10–3.13 (see .github/workflows/ci.yml).

License

GPL.