Full-featured Jalali (Persian/Shamsi) calendar support for pandas — A complete pandas extension providing native Jalali datetime types, time series operations, and calendar-aware functionality.
- JalaliTimestamp: Full-featured scalar type with all date/time properties
- JalaliDatetimeDtype: Registered pandas extension dtype (
jalali_datetime64[ns]) - JalaliDatetimeArray: Extension array for Series storage with vectorized operations
- JalaliDatetimeIndex: Complete pandas Index implementation with Jalali awareness
- jalali_date_range(): Generate date ranges with frequency support (daily, monthly, quarterly, yearly)
- to_jalali_datetime() / to_gregorian_datetime(): Bidirectional conversion for all input types
- String parsing with multiple formats:
"1402-06-15","1402/6/15","1402-06","1402"
- JalaliMonthEnd/Begin: Handle Jalali month boundaries (31-day months 1-6, 30-day months 7-11, Esfand 29/30)
- JalaliQuarterEnd/Begin: Quarter boundaries respecting Jalali calendar
- JalaliYearEnd/Begin: Year boundaries (1 Farvardin start, 29/30 Esfand end)
- JalaliWeek: Saturday-based weeks with custom weekday support
- Frequency aliases:
JME,JMS,JQE,JQS,JYE,JYS,JW
- resample_jalali(): Jalali-aware resampling with proper calendar boundaries
- JalaliGrouper: Calendar-based grouping by year/month/quarter/day
- Enhanced Accessors: Full Series and DataFrame accessor support
- Properties:
year,month,day,quarter,week,weekday,is_leap_year, etc. - Methods:
strftime(),normalize(),floor(),ceil(),round(),tz_localize(),tz_convert()
- Properties:
- 94% test coverage with 563+ passing tests
- Type hints throughout (PEP 561 compliant)
- Python 3.9-3.13 support
- pandas 2.0-2.2 compatibility
pip install jalali-pandasFor development:
pip install jalali-pandas[dev]uv add jalali-pandasFor development:
uv add --dev jalali-pandasimport pandas as pd
import jalali_pandas
from jalali_pandas import jalali_date_range, to_jalali_datetime
# Create a Jalali date range
jdates = jalali_date_range("1402-01-01", periods=10, freq="D")
print(jdates)
# JalaliDatetimeIndex(['1402-01-01', '1402-01-02', ..., '1402-01-10'], dtype='jalali_datetime64[ns]', freq='D')
# Convert Gregorian to Jalali
gregorian_dates = pd.date_range("2023-01-01", periods=5)
jalali_dates = to_jalali_datetime(gregorian_dates)
print(jalali_dates)
# JalaliDatetimeIndex(['1401-10-11', '1401-10-12', ..., '1401-10-15'], dtype='jalali_datetime64[ns]')import pandas as pd
import jalali_pandas
# Create a DataFrame with Gregorian dates
df = pd.DataFrame({
"date": pd.date_range("2023-01-01", periods=10, freq="D"),
"value": range(10)
})
# Convert to Jalali using accessor
df["jdate"] = df["date"].jalali.to_jalali()
# Access Jalali date components
df["year"] = df["jdate"].jalali.year
df["month"] = df["jdate"].jalali.month
df["day"] = df["jdate"].jalali.day
df["quarter"] = df["jdate"].jalali.quarter
df["weekday"] = df["jdate"].jalali.weekday
df["is_leap"] = df["jdate"].jalali.is_leap_year
# Format as Persian strings
df["persian_date"] = df["jdate"].jalali.strftime("%Y/%m/%d")import pandas as pd
import jalali_pandas
from jalali_pandas import jalali_date_range
# Create DataFrame with Jalali dates
df = pd.DataFrame({
"date": jalali_date_range("1402-01-01", periods=100, freq="D"),
"value": range(100)
})
# Group by Jalali year and month
monthly = df.jalali.groupby(["year", "month"]).sum()
# Use shortcuts for common groupings
yearly = df.jalali.groupby("year").mean() # Group by year
quarterly = df.jalali.groupby("yq").sum() # Group by year-quarter
daily = df.jalali.groupby("ymd").count() # Group by year-month-day
# Resample with Jalali calendar awareness
monthly_resample = df.set_index("date").resample_jalali("JME").sum()
quarterly_resample = df.set_index("date").resample_jalali("JQE").mean()from jalali_pandas import JalaliTimestamp
from jalali_pandas.offsets import JalaliMonthEnd, JalaliYearEnd
# Create Jalali timestamps
jts = JalaliTimestamp(1402, 6, 15, 12, 30, 0)
print(jts.strftime("%Y/%m/%d %H:%M")) # 1402/06/15 12:30
# Use frequency offsets
end_of_month = jts + JalaliMonthEnd()
end_of_year = jts + JalaliYearEnd()
# Timezone support
jts_tehran = jts.tz_localize("Asia/Tehran")
jts_utc = jts_tehran.tz_convert("UTC")- Full Documentation: https://ghodsizadeh.github.io/jalali-pandas/
- API Reference: https://ghodsizadeh.github.io/jalali-pandas/en/api/
- Examples: 11 Python examples + 2 Jupyter notebooks
- Persian Documentation: مستندات فارسی
Contributions are welcome! Please read our Contributing Guide for details.
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
- Built on top of pandas and jdatetime
- Inspired by the need for proper Jalali calendar support in data analysis
برای مطالعه راهنمای فارسی استفاده از کتابخانه به این آدرس مراجعه کنید:
- مستندات کامل: https://ghodsizadeh.github.io/jalali-pandas/fa/
- راهنمای نصب: نصب و راهاندازی
- آموزش سریع: شروع سریع
- مقاله آموزشی: معرفی بسته pandas-jalali | آموزش کار با تاریخ شمسی در pandas