{"id":21480,"library":"jdatetime","title":"jdatetime - Jalali (Persian) datetime library","description":"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.","status":"active","version":"5.2.0","language":"python","source_language":"en","source_url":"https://github.com/slashmili/python-jalali","tags":["jalali","persian","calendar","datetime","iranian"],"install":[{"cmd":"pip install jdatetime","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"note":"JalaliDatetime is an alias but import jdatetime is the canonical way.","wrong":"from jdatetime import JalaliDatetime","symbol":"jdatetime","correct":"import jdatetime"},{"note":"Direct import of date class is simpler; internal module path is not public.","wrong":"from jdatetime.jalali import JalaliDate","symbol":"date","correct":"from jdatetime import date"},{"note":"JalaliDatetime is an alias; datetime is the class name.","wrong":"from jdatetime import JalaliDatetime","symbol":"datetime","correct":"from jdatetime import datetime"}],"quickstart":{"code":"import jdatetime\ntoday = jdatetime.date.today()\nprint(today)\ndt = jdatetime.datetime(1402, 12, 1, 10, 30, 0)\nprint(dt.strftime('%Y-%m-%d %H:%M:%S'))","lang":"python","description":"Create and format Jalali dates and times."},"warnings":[{"fix":"Review code that uses %% in format strings; ensure it is intended as a literal percent.","message":"In jdatetime >=5.0.0, the strftime/strptime escape handling changed: %% is treated as an escape sequence. Previously %% might not have been handled correctly.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade to Python 3.9+ or pin jdatetime to <5.1.0 if stuck on Python 3.8.","message":"Python 3.8 support dropped in v5.1.0. jdatetime 5.0.0 was the last version supporting Python 3.8.","severity":"breaking","affected_versions":">=5.1.0"},{"fix":"Convert via .togregorian() method before mixing with standard datetime objects.","message":"jdatetime.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.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure you need Jalali output; use standard datetime.fromtimestamp() for Gregorian.","message":"jdatetime.datetime.fromtimestamp() accepts a POSIX timestamp (seconds since epoch) but returns a Jalali datetime. Many users expect it to return Gregorian.","severity":"gotcha","affected_versions":"all"},{"fix":"Use 'date' and 'datetime' from jdatetime directly.","message":"The alias 'JalaliDate' and 'JalaliDatetime' are deprecated since v4.0.0 and may be removed in future versions.","severity":"deprecated","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use `from jdatetime import datetime` or `import jdatetime; jdatetime.datetime`.","cause":"Importing jdatetime alone does not expose datetime class directly; you must import from jdatetime.","error":"AttributeError: module 'jdatetime' has no attribute 'datetime'"},{"fix":"Convert one side: `jdt.togregorian()` or compare after conversion.","cause":"jdatetime and standard datetime types are incompatible for comparison.","error":"TypeError: can't compare datetime.datetime to jdatetime.datetime"},{"fix":"Ensure you are using correct Jalali month/day values when constructing jdatetime objects.","cause":"Jalali months have different lengths; using Gregorian day numbers directly can cause this.","error":"ValueError: day is out of range for month"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}