Metadata-Version: 2.4
Name: pyroj
Version: 1.2.2
Summary: Kurdish solar calendar and conversions (Gregorian, Persian/Jalali, tabular Islamic) using the Python standard library only.
Author: Dolan Hêriş
License: AGPL-3.0-only
Project-URL: Homepage, https://github.com/0xdolan/pyroj
Keywords: kurdish,kurdistan,kurdish-calendar,sorani,kurmanji,datetime,date,time,calendar,jalali,persian,islamic,hijri,gregorian,roj,rojjmer
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Internationalization
Classifier: Topic :: Software Development :: Localization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Dynamic: license-file

# 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](docs/KURDISH_DATE_CALCULATION.md).

## 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!

```bash
uv pip install pyroj
# or
pip install pyroj
```

### Basic Creation and Conversions
```python
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!

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

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

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

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

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

Install the package locally for development:

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