jdatetime

library5.3.0pypypi✓ verified 92d ago

jdatetime provides Jalali (Persian, Solar Hijri) calendar support for Python, mirroring Python's datetime interface. Current version 5.2.0 supports Python >=3.9. Release cadence is irregular; major versions drop old Python versions.

serialization

pip install jdatetime

github ↗package ↗

INSTALL

IMPORT

SIG · JDATETIME

jdatetime

serializationpythonv5.3.0

Install

1.5s avg

Import

26ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.030s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.022s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jdatetime

✓ import jdatetime

✗ from jdatetime import JalaliDatetime

JalaliDatetime is an alias but import jdatetime is the canonical way.

date

✓ from jdatetime import date

✗ from jdatetime.jalali import JalaliDate

Direct import of date class is simpler; internal module path is not public.

datetime

✓ from jdatetime import datetime

✗ from jdatetime import JalaliDatetime

JalaliDatetime is an alias; datetime is the class name.

Create and format Jalali dates and times.

import jdatetime today = jdatetime.date.today() print(today) dt = jdatetime.datetime(1402, 12, 1, 10, 30, 0) print(dt.strftime('%Y-%m-%d %H:%M:%S'))

Debug

Known issues

breakingIn jdatetime >=5.0.0, the strftime/strptime escape handling changed: %% is treated as an escape sequence. Previously %% might not have been handled correctly.

fix

Review code that uses %% in format strings; ensure it is intended as a literal percent.

affects: >=5.0.0

breakingPython 3.8 support dropped in v5.1.0. jdatetime 5.0.0 was the last version supporting Python 3.8.

fix

Upgrade to Python 3.9+ or pin jdatetime to <5.1.0 if stuck on Python 3.8.

affects: >=5.1.0

gotchajdatetime.date and jdatetime.datetime are not subclasses of Python's datetime.date/datetime; direct comparison or arithmetic with standard datetime types may raise TypeError or produce unexpected results.

fix

Convert via .togregorian() method before mixing with standard datetime objects.

affects: all

gotchajdatetime.datetime.fromtimestamp() accepts a POSIX timestamp (seconds since epoch) but returns a Jalali datetime. Many users expect it to return Gregorian.

fix

Ensure you need Jalali output; use standard datetime.fromtimestamp() for Gregorian.

affects: all

deprecatedThe alias 'JalaliDate' and 'JalaliDatetime' are deprecated since v4.0.0 and may be removed in future versions.

fix

Use 'date' and 'datetime' from jdatetime directly.

affects: >=4.0.0

Errors

Common errors & fixes

AttributeError: module 'jdatetime' has no attribute 'datetime'

Importing jdatetime alone does not expose datetime class directly; you must import from jdatetime.

fix

Use `from jdatetime import datetime` or `import jdatetime; jdatetime.datetime`.

TypeError: can't compare datetime.datetime to jdatetime.datetime

jdatetime and standard datetime types are incompatible for comparison.

fix

Convert one side: `jdt.togregorian()` or compare after conversion.

ValueError: day is out of range for month

Jalali months have different lengths; using Gregorian day numbers directly can cause this.

fix

Ensure you are using correct Jalali month/day values when constructing jdatetime objects.

Upgrade

Version history

5.3.0latest on PyPI · released May 19, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Anthropic

Resources

githubhttps://github.com/slashmili/python-jalali ↗

packagehttps://pypi.org/project/jdatetime/ ↗