jdatetime

What it is and what it does

jdatetime is a drop-in Jalali calendar replacement for Python's datetime module, designed for applications that need to work with the Iranian calendar system. It provides date and datetime objects that behave identically to their standard library counterparts, but represent dates in the Jalali calendar instead of the Gregorian calendar. The package includes bidirectional conversion between Gregorian and Jalali dates, leap-year detection, and locale support for displaying dates in Farsi.

The library is built on top of jalali-core and follows Python's datetime API closely, so developers familiar with the standard library can use it with minimal learning curve. It supports per-instance and process-wide locale configuration, making it suitable for applications that need to display dates in both English and Farsi, or that serve users in different locales within the same process.

Use it for:

• Build applications for Iranian users that display dates in the Jalali calendar and Farsi language.
• Convert between Gregorian and Jalali dates when integrating with systems that use both calendar systems.
• Schedule events and store timestamps using the Iranian calendar in databases or APIs.
• Generate reports or invoices with dates formatted in the Jalali calendar for Persian-speaking markets.
• Handle date arithmetic while staying within the Jalali calendar system.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

jdatetime provides a Jalali (Persian) calendar implementation that mirrors Python's standard datetime module, allowing you to work with dates and times in the Iranian calendar system.

Yes. jdatetime is actively maintained, has no known vulnerabilities, installs with minimal friction, and fills a clear need for Persian calendar support. The permissive PSF-2.0 license and support for modern Python versions make it a safe choice for production use in applications serving Iranian users or handling Jalali dates.

Install

jdatetime on PyPI

pip install jdatetime

uv add jdatetime

poetry add jdatetime

Installing jdatetime

Before you install

Low friction installation with a single runtime dependency (jalali-core). The project is actively maintained with a recent release and steady commit activity.

License in practice

Licensed under PSF-2.0 (permissive), allowing free use, modification, and distribution with minimal restrictions.

Quickstart

pip install jdatetime

import jdatetime

# Get current Jalali date and time
print(jdatetime.datetime.now())
print(jdatetime.date.today())

# Convert from Gregorian
gregorian_date = jdatetime.date.fromgregorian(day=1, month=1, year=1)
print(gregorian_date)

Requires Python 3.9 or later.

Verify before relying

• Whether locale support works reliably across all supported Python versions.
• Performance characteristics when handling large volumes of date conversions or arithmetic operations.
• Thread-safety guarantees for the per-thread locale setting mechanism mentioned in the documentation.

Package facts

Evidence: jdatetime-6.1.0-py3-none-any.whl

Keywords: Jalali, implementation, of, Python, datetime

Tags

More Software Development packages