jalali-core

1.0.0 verified Mon Apr 27 auth: no python

A Python library for converting between Gregorian and Jalali (Persian/Solar Hijri) dates, targeting Python 3.8+. Version 1.0.0 is the first stable release, with a focus on simplicity and correctness. The library provides a single core function for conversion and is designed to be lightweight with no external dependencies. Release cadence is not yet established.

pip install jalali-core

Common errors

error ModuleNotFoundError: No module named 'jalali_core' ↓

cause Wrong import path: some may try 'import jalali' or 'import jalali_core' but the package name is 'jalali-core' (with hyphen) and module is 'jalali_core'.

fix

Install with pip install jalali-core, then import as from jalali_core import ....

error TypeError: cannot unpack non-iterable datetime.date object ↓

cause Passing a single datetime.date object to JalaliToGregorian instead of a tuple (year, month, day).

fix

Use JalaliToGregorian()( (year, month, day) ) with a tuple argument.

Warnings

gotcha Jalali year zero does not exist. The library expects years in the usual Jalali calendar with 1-based years (e.g., 1404). Do not pass year 0. ↓

fix Ensure Jalali years are positive (>= 1).

gotcha Input dates must be valid. The library does not validate Jalali dates; passing invalid dates (e.g., month 13) may produce incorrect results or raise exceptions. ↓

fix Validate Jalali dates yourself before conversion (e.g., month 1-12, day according to month).

Imports

GregorianToJalali
wrong
```
import jalali_core
```
correct
```
from jalali_core import GregorianToJalali
```
Wrong: module not imported correctly. Use from import.

JalaliToGregorian

from jalali_core import JalaliToGregorian

Quickstart

Basic conversion between Gregorian and Jalali dates.

from jalali_core import GregorianToJalali, JalaliToGregorian
import datetime

g2j = GregorianToJalali()
gregorian_date = datetime.date(2025, 4, 27)
jalali_date = g2j(gregorian_date)
print(f"Gregorian {gregorian_date} -> Jalali {jalali_date}")

j2g = JalaliToGregorian()
jalali_date = (1404, 2, 7)
gregorian_date = j2g(jalali_date)
print(f"Jalali {jalali_date} -> Gregorian {gregorian_date}")