Skip to main content

JalaliX

Jalali (Persian / Shamsi) calendar for Python. Pure Python 3.9+, no runtime dependencies.

PyPI license

pip install jalalix
from jalalix import JalaliX

date = JalaliX.create('2025-02-25')

date.format('YYYY/MM/DD')  # 1403/12/07
date.format('DD MMM YYYY', {'persianDigits': True})  # ۰۷ اسفند ۱۴۰۳

JalaliX.parseJalali('1403/12/07').toISODate()  # 2025-02-25

toISODate() uses local calendar getters. Prefer it when you need a calendar date string without UTC shift surprises.

Install

pip install jalalix
from jalalix import JalaliX

Usage

create / format

now = JalaliX.create(datetime.now(), {'timezone': 'Asia/Tehran'})

now.format('YYYY/MM/DD')
now.format('WN، DD MMM YYYY')
now.format('YYYY/MM/DD', {'persianDigits': True})
now.format('DD MMM YYYY', {'calendar': 'gregorian'})

format also accepts the older positional form: format(str, persianDigits?, gregorian?).

parseJalali

JalaliX.parseJalali('1403/12/07')
JalaliX.parseJalali('۱۴۰۳-۱۲-۰۷ 14:30')

toISODate

d = JalaliX.create('2025-02-25')

d.toISODate()          # 2025-02-25  (local Gregorian getters)
d.toISODate('jalali')  # 1403-12-07

add / start / end

JalaliX.create('2025-02-25').addMonths(1).getStartOfMonth().format('YYYY/MM/DD')

Persian digits

JalaliX.toPersian('1403/12/07')   # ۱۴۰۳/۱۲/۰۷
JalaliX.fromPersian('۱۴۰۳/۱۲/۰۷')  # 1403/12/07

Months

This is easy to get wrong:

  • getMonth() -> 1..12 (Farvardin = 1)
  • setMonth(m) / setFullYear(y, m) -> 0..11, same as JS Date (Farvardin = 0)
d = JalaliX.create(datetime.now())
d.setFullYear(1404, 0, 1)  # 1 Farvardin 1404
d.getMonth()  # 1

Timezone

Internal storage is a UTC Unix millisecond instant plus an IANA timezone id. setTimezone is instant-preserving: the timestamp stays the same; wall clock / Jalali day may change.

d = JalaliX.create(1740430800000)
tehran = d.setTimezone("Asia/Tehran")
tehran.format("YYYY/MM/DD")  # 1403/12/07
tehran.format("HH:mm:ss")    # 00:30:00

utc = d.setTimezone("UTC")
utc.format("YYYY/MM/DD")  # 1403/12/06
utc.format("HH:mm:ss")    # 21:00:00
  • Aliases: utc / gmt -> UTC; local / default / system -> host IANA zone when detectable, else UTC.
  • Invalid zone -> ValueError.
  • Offsets use stdlib zoneinfo, with a vendored TZif set under jalalix/zoneinfo/ (UTC, Etc/UTC, Asia/Tehran, Asia/Tokyo, Europe/London, America/New_York) so Windows works without the PyPI tzdata package.

Format tokens

Token
YYYY YY year
MMM MM M month name / number
DD D day
HH hh mm ss time
A a meridiem (ق.ظ. / ب.ظ. or AM/PM)
WN WL weekday name / letter
w DDD week of year / day of year
X x unix seconds / ms
date.format('YYYY/MM/DD')
date.format('YYYY/MM/DD', {'persianDigits': True})
date.format('DD MMM YYYY', {'calendar': 'gregorian'})

API

Static:

  • create(date, options?) — timestamp (ms), ISO string, datetime, or date
  • parseJalali(str, options?)
  • isValidDate(value)
  • toPersian(str) / fromPersian(str)
  • compare(a, b) — true if a is before b

options is {'timezone': str} (e.g. 'Asia/Tehran').

Instance (main ones):

  • format(...), toISODate(calendar?)
  • toString(), toDateString(), toLocaleDateString(), toLocaleTimeString()
  • getFullYear(), getMonth(), getDate(), getDay(), …
  • setFullYear, setMonth, setDate, setHours, … (mutate and return self)
  • addYears, addMonths, addWeeks, addDays
  • getStartOfYear / Month / Week / Day and matching getEndOf*
  • clone(), setTimezone(tz), getTimezone()

Method names match the TypeScript package (camelCase).

License

MIT

Metadata

Release files for jalalix 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jalalix 0.1.0
File Size Uploaded Provenance Actions
jalalix-0.1.0.tar.gz 32.3 kB Without provenance Details for jalalix-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jalalix 0.1.0
File Interpreter ABI Platform Actions
jalalix-0.1.0-py3-none-any.whl Python 3 none any Details for jalalix-0.1.0-py3-none-any.whl

Total release size: 51.3 kB

Release files / jalalix-0.1.0.tar.gz

Download URL jalalix-0.1.0.tar.gz
Size 32.3 kB
Tags Source
SHA-256 checksum
How to use checksums
b51a623c88141270fb379709250aa446261a430643a8752ca190a51d9e89f84e
BLAKE2b-256 checksum
How to use checksums
654595f01dec73a93bcd23754cbcb6a4b3ad5dddc33b5a2ef51244834cf6d9b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Release files / jalalix-0.1.0-py3-none-any.whl

Download URL jalalix-0.1.0-py3-none-any.whl
Size 18.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4ade69b6c51621a94b762f0b702dcafe407eebf81fdd2dd764ce3f5d961700df
BLAKE2b-256 checksum
How to use checksums
4b9b6893333dfc83d859443bfe25232c53a3569d3feaa1aa0236812d837566ab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Security for jalalix 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page