JalaliX - Python
Jalali (Persian / Shamsi) calendar on top of a millisecond Unix timestamp. Pure Python 3.9+, no runtime dependencies.
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 wall-clock getters in the active timezone. Prefer it over UTC-based slicing when you need a calendar date string.
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')
JalaliX.parseJalali('1403.12.07')
Named parseJalali because built-in datetime already covers Gregorian parsing. Accepts /, -, or . as the date separator.
normalizeQueryDate
Soft-normalize loose API/query date values to a Gregorian Y-m-d H:i:s string (or None). Does not raise on junk input.
JalaliX.normalizeQueryDate('1403/12/07', {'timezone': 'Asia/Tehran'})
# '2025-02-25 00:00:00'
JalaliX.normalizeQueryDate('undefined') # None
JalaliX.normalizeQueryDate(1740430800000, {'timezone': 'Asia/Tehran'})
# '2025-02-25 00:30:00'
Handles sentinels (None, '', 'null', 'undefined', 'Invalid Date', NaN) → None; unix timestamps (seconds or milliseconds; non-positive → None); Persian/Arabic-Indic digits; / - . separators; fractional seconds; optional Z / offset suffixes.
Detects Jalali when the year is in jalaliYearMin…jalaliYearMax (default 1…1899) and the civil date is valid; otherwise Gregorian when valid, or returns the digit-cleaned string. Non-string/non-number values pass through unchanged.
toISODate
d = JalaliX.create('2025-02-25T00:30:00+03:30')
d.toISODate() # 2025-02-25
d.toISODate('jalali') # 1403-12-07
add / start / end
JalaliX.create('2025-02-25').addMonths(1).getStartOfMonth().format('YYYY/MM/DD')
# e.g. 1404/01/01
d = JalaliX.create('2025-02-25', {'timezone': 'Asia/Tehran'})
d.addDays(7).format('YYYY/MM/DD')
d.getEndOfWeek().format('YYYY/MM/DD')
Persian / Arabic digits
JalaliX.toPersian('1403/12/07') # ۱۴۰۳/۱۲/۰۷
JalaliX.fromPersian('۱۴۰۳/۱۲/۰۷') # 1403/12/07
JalaliX.fromPersian('١٤٠٣/١٢/٠٧') # 1403/12/07 (Arabic-Indic)
Timezone
Internal storage is always a UTC Unix millisecond instant plus an IANA timezone id. setTimezone is instant-preserving: the timestamp stays the same; only the zone (and therefore wall clock / Jalali day) changes.
d = JalaliX.create(1740430800000) # 2025-02-25T00:30:00+03:30
tehran = d.setTimezone('Asia/Tehran')
tehran.format('YYYY/MM/DD') # 1403/12/07
tehran.format('HH:mm') # 00:30
utc = d.setTimezone('UTC')
utc.format('YYYY/MM/DD') # 1403/12/06
utc.format('HH:mm') # 21:00
tehran.getTime() == utc.getTime() # True
- Aliases:
utc/gmt→UTC;local/default/system→ host IANA when detectable, elseUTC. - Invalid zone →
ValueError. - Offsets use stdlib
zoneinfo, with a vendored TZif set underjalalix/zoneinfo/(UTC,Etc/UTC,Asia/Tehran,Asia/Tokyo,Europe/London,America/New_York) so Windows works without the PyPItzdatapackage.
JalaliX.create(datetime.now(), {'timezone': 'Asia/Tehran'})
Months
Easy to get wrong:
getMonth()→ 1…12 (Farvardin = 1)setMonth(m)/setFullYear(y, m)→ 0…11, same as JSDate(Farvardin = 0)
d = JalaliX.create(datetime.now())
d.setFullYear(1404, 0, 1) # 1 Farvardin 1404
d.getMonth() # 1
Format tokens
| Token | Meaning |
|---|---|
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 / - |
API -
Method names match the TypeScript packa - (camelCase).
Static
| API | Description |
|---|---|
create(date, options?) |
Build from unix ms, ISO/YYYY-MM-DD string, datetime, date, or JalaliX. Optional {'timezone': str}. |
parseJalali(str, options?) |
Parse a Jalali date/time string (/ - ., Persian/Arabic digits, optional time). |
normalizeQueryDate(value, options?) |
Soft-normalize loose query/form values → Gregorian Y-m-d H:i:s or None. Options: timezone, jalaliYearMin, jalaliYearMax (defaults 1…1899). |
isValidDate(value) |
True if value is a JalaliX, datetime, or date instance. |
toPersian(str) |
Replace Western digits 0-9 with Persian ۰-۹. |
fromPersian(str) |
Replace Persian ۰-۹ and Arabic-Indic ٠-٩ with Western digits. |
compare(a, b) |
True if a is strictly before b (by unix ms). |
persianNumbers |
List of Persian digit characters ۰…۹. |
arabicNumbers |
List of Arabic-Indic digit characters ٠…٩. |
Constructor
| API | Description |
|---|---|
JalaliX(ms?) |
Build from optional millisecond timestamp; timezone defaults to UTC. |
Instance - getters
| API | Description |
|---|---|
getFullYear() |
Jalali year in the active timezone. |
getMonth() |
Jalali month 1…12 (Farvardin = 1). |
getDate() |
Jalali day of month 1…31. |
getDay() |
Weekday 1…7 (Saturday = 1 … Friday = 7). |
getHours() / getMinutes() / getSeconds() / getMilliseconds() |
Wall-clock time in the active timezone. |
getTime() |
Unix timestamp in milliseconds (UTC instant). |
getTimezone() |
Active IANA timezone id. |
getWeekOfYear() |
Jalali week-of-year (1-based). |
getDayOfYear() |
Day of Jalali year (1…365/366). |
getDayISO() |
ISO-style weekday index used internally for week math. |
getHoursISO() |
Hours in 0…23 for formatting helpers. |
getMeridiem() |
Localized meridiem string (ق.ظ./ب.ظ. or AM/PM depending on calendar). |
Instance - setters
| API | Description |
|---|---|
setTime(ms) |
Set the UTC instant from unix milliseconds. |
setMilliseconds(ms) |
Set milliseconds (wall clock). |
setSeconds(sec, ms?) |
Set seconds (and optional ms). |
setMinutes(min, sec?, ms?) |
Set minutes (and optional lower units). |
setHours(h, min?, sec?, ms?) |
Set hours (and optional lower units). |
setDate(day) |
Set Jalali day of month. |
setMonth(month, date?) |
Set Jalali month 0…11 (Farvardin = 0); optional day. |
setFullYear(year, month?, date?) |
Set Jalali year; optional month 0…11 and day. |
setTimezone(tz) |
Instant-preserving zone change; returns a new instance. |
Instance - math, range, format
| API | Description |
|---|---|
addYears(n) / addMonths(n) / addWeeks(n) / addDays(n) |
Add calendar units; mutate and return self. |
getStartOfYear() / getStartOfMonth() / getStartOfWeek() / getStartOfDay() |
Start of unit (new instance). |
getEndOfYear() / getEndOfMonth() / getEndOfWeek() / getEndOfDay() |
End of unit (new instance). |
format(str, options?) |
Format with tokens above; options {'calendar', 'persianDigits'} or positional booleans. |
toISODate(calendar?) |
YYYY-MM-DD in 'gregorian' (default) or 'jalali'. |
clone() |
Copy with the same instant and timezone. |
__str__() / toString() / toDateString() / toLocaleDateString() / toLocaleTimeString() |
String views of the date/time. |
__repr__() |
Debug representation of the instance. |
Links
- https://pypi.org/project/jalalix/
- https://jalalix.com
- https://github.com/jalalix/python
- CHANGELOG.md
License
MIT
Metadata
Release files for jalalix 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jalalix-0.2.0.tar.gz | 25.9 kB | Without provenance | Details for jalalix-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jalalix-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for jalalix-0.2.0-py3-none-any.whl |
Total release size: 47.9 kB
Release files / jalalix-0.2.0.tar.gz
| Download URL | jalalix-0.2.0.tar.gz |
|---|---|
| Size | 25.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
455ea30f76001a41007d909afe144a5790ffe3724acfc61cc668c04149c2c5e5
|
|
BLAKE2b-256 checksum How to use checksums |
e9449897909587e64a729775f6e68ed6dd023c9ef877bba47a9607a0eaa4318f
|
| 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.2.0-py3-none-any.whl
| Download URL | jalalix-0.2.0-py3-none-any.whl |
|---|---|
| Size | 22.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0a27873573cb2deb4d4c3fd27a4fd3cc2bc20cb4e85e8f9fcb89787e2c979100
|
|
BLAKE2b-256 checksum How to use checksums |
a0cfb865666bad3dc37c335838eeb4e989044340269fab32b8ebaf3530eab97b
|
| 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.2.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.