Jalali Pandas Extension

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.

Jalali Pandas python package

✨ Features

🎯 Core Types

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

📅 Date Range & Conversion

jalalidaterange(): Generate date ranges with frequency support (daily, monthly, quarterly, yearly)
tojalalidatetime() / togregoriandatetime(): Bidirectional conversion for all input types
String parsing with multiple formats: "1402-06-15", "1402/6/15", "1402-06", "1402"

🔄 Frequency Offsets

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

📊 Time Series Operations

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, isleapyear, etc. - Methods: strftime(), normalize(), floor(), ceil(), round(), tzlocalize(), tzconvert()

🧪 Quality & Performance

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

📦 Installation

Using pip

pip install jalali-pandas

For development:

pip install jalali-pandas[dev]

Using uv (recommended for faster installation)

uv add jalali-pandas

For development:

uv add --dev jalali-pandas

🚀 Quick Start

Basic Usage

import pandas as pd
import jalali_pandas
from jalalipandas import jalalidaterange, tojalali_datetime
Create a Jalali date range
jdates = jalalidaterange("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
gregoriandates = pd.daterange("2023-01-01", periods=5)
jalalidates = tojalalidatetime(gregoriandates)
print(jalali_dates)
JalaliDatetimeIndex(['1401-10-11', '1401-10-12', ..., '1401-10-15'], dtype='jalali_datetime64[ns]')

Series Operations

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["isleap"] = df["jdate"].jalali.isleap_year
Format as Persian strings
df["persian_date"] = df["jdate"].jalali.strftime("%Y/%m/%d")

DataFrame Operations

import pandas as pd
import jalali_pandas
from jalalipandas import jalalidate_range
Create DataFrame with Jalali dates
df = pd.DataFrame({
    "date": jalalidaterange("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
monthlyresample = df.setindex("date").resample_jalali("JME").sum()
quarterlyresample = df.setindex("date").resample_jalali("JQE").mean()

Advanced Features

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
endofmonth = jts + JalaliMonthEnd()
endofyear = jts + JalaliYearEnd()
Timezone support
jtstehran = jts.tzlocalize("Asia/Tehran")
jtsutc = jtstehran.tz_convert("UTC")