JalaliX
Jalali (Persian / Shamsi) calendar for Python. 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 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 JSDate(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, 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.
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, ordateparseJalali(str, options?)isValidDate(value)toPersian(str)/fromPersian(str)compare(a, b)— true ifais beforeb
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 returnself)addYears,addMonths,addWeeks,addDaysgetStartOfYear/Month/Week/Dayand matchinggetEndOf*clone(),setTimezone(tz),getTimezone()
Method names match the TypeScript package (camelCase).
Links
- https://pypi.org/project/jalalix/
- https://jalalix.com
- https://github.com/jalalix/python
- CHANGELOG.md
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.