0
# Calendar Systems
1

2
Support for non-Gregorian calendar systems including Islamic (Hijri) and Persian (Jalali) calendars for parsing dates in different cultural contexts. These calendar systems extend dateparser's capabilities beyond the standard Gregorian calendar.
3

4
## Capabilities
5

6
### Hijri Calendar Support
7

8
Islamic calendar system support for parsing Hijri dates and converting them to Gregorian datetime objects.
9

10
```python { .api }
11
class HijriCalendar(CalendarBase):
12
    """
13
    Support for Hijri (Islamic) calendar dates.
14
    
15
    Converts Hijri dates to Gregorian datetime objects while preserving
16
    the original calendar context for accurate date parsing.
17
    """
18
    
19
    def __init__(self, source):
20
        """
21
        Initialize Hijri calendar parser.
22
        
23
        Parameters:
24
        - source (str): Date string in Hijri format
25
        """
26
    
27
    def get_date(self):
28
        """
29
        Parse Hijri date string and convert to DateData object.
30
        
31
        Returns:
32
        DateData: Object containing converted Gregorian datetime
33
        """
34
```
35

36
**Usage Examples:**
37

38
```python
39
from dateparser.calendars.hijri import HijriCalendar
40

41
# Parse Hijri dates
42
hijri_date = "15 محرم 1445"  # 15 Muharram 1445
43
calendar = HijriCalendar(hijri_date)
44
date_data = calendar.get_date()
45
gregorian_date = date_data.date_obj  # Converted to Gregorian
46

47
# Integration with main dateparser
48
import dateparser
49

50
# Configure settings for Hijri calendar support
51
settings = {'CALENDARS': ['hijri']}
52
date = dateparser.parse("15 محرم 1445", settings=settings)
53
```
54

55
### Jalali Calendar Support
56

57
Persian calendar system support for parsing Jalali (Solar Hijri) dates used in Iran and Afghanistan.
58

59
```python { .api }
60
class JalaliCalendar(CalendarBase):
61
    """
62
    Support for Jalali (Persian) calendar dates.
63
    
64
    Handles Solar Hijri calendar dates and converts them to
65
    Gregorian datetime objects for standardized processing.
66
    """
67
    
68
    def __init__(self, source):
69
        """
70
        Initialize Jalali calendar parser.
71
        
72
        Parameters:
73
        - source (str): Date string in Jalali format
74
        """
75
    
76
    def get_date(self):
77
        """
78
        Parse Jalali date string and convert to DateData object.
79
        
80
        Returns:
81
        DateData: Object containing converted Gregorian datetime
82
        """
83
```
84

85
**Usage Examples:**
86

87
```python
88
from dateparser.calendars.jalali import JalaliCalendar
89

90
# Parse Persian/Jalali dates
91
jalali_date = "15 فروردین 1402"  # 15 Farvardin 1402
92
calendar = JalaliCalendar(jalali_date)
93
date_data = calendar.get_date()
94
gregorian_date = date_data.date_obj  # Converted to Gregorian
95

96
# Integration with main dateparser
97
import dateparser
98

99
# Configure settings for Jalali calendar support
100
settings = {'CALENDARS': ['jalali']}  
101
date = dateparser.parse("15 فروردین 1402", settings=settings)
102
```
103

104
### Base Calendar System
105

106
Abstract base class for implementing custom calendar systems and extending dateparser with additional calendar support.
107

108
```python { .api }
109
class CalendarBase:
110
    """
111
    Base setup class for non-Gregorian calendar system.
112
    
113
    Provides the framework for implementing custom calendar parsers
114
    that can integrate with dateparser's main parsing pipeline.
115
    """
116
    
117
    parser = NotImplemented  # Must be implemented by subclasses
118
    
119
    def __init__(self, source):
120
        """
121
        Initialize calendar parser with source date string.
122
        
123
        Parameters:
124
        - source (str): Date string passed to calendar parser
125
        """
126
    
127
    def get_date(self):
128
        """
129
        Parse date string and return DateData object.
130
        
131
        Returns:
132
        DateData: Parsed date information, or None if parsing fails
133
        """
134
```
135

136
**Usage Examples:**
137

138
```python
139
from dateparser.calendars import CalendarBase
140
from dateparser.date import DateData
141

142
# Example custom calendar implementation
143
class CustomCalendar(CalendarBase):
144
    def __init__(self, source):
145
        super().__init__(source)
146
        # Initialize custom calendar logic
147
    
148
    def get_date(self):
149
        try:
150
            # Custom parsing logic
151
            parsed_date = self.parse_custom_format(self.source)
152
            return DateData(date_obj=parsed_date)
153
        except ValueError:
154
            return None
155
    
156
    def parse_custom_format(self, date_string):
157
        # Implement custom parsing logic
158
        pass
159

160
# Use custom calendar
161
custom_date = "CustomFormat:2023:01:15"
162
calendar = CustomCalendar(custom_date)
163
date_data = calendar.get_date()
164
```
165

166
### Calendar Parser Classes
167

168
Lower-level parser classes that handle the actual conversion logic for specific calendar systems.
169

170
```python { .api }
171
class hijri_parser(non_gregorian_parser):
172
    """
173
    Hijri calendar parser implementation.
174
    
175
    Handles conversion between Hijri calendar dates and Gregorian
176
    calendar dates with proper month, day, and year mapping.
177
    """
178
    
179
    calendar_converter = NotImplemented  # Hijri to Gregorian converter
180
    default_year: int
181
    default_month: int  
182
    default_day: int
183

184
class jalali_parser(non_gregorian_parser):
185
    """
186
    Jalali calendar parser implementation.
187
    
188
    Handles conversion between Persian Solar Hijri calendar dates
189
    and Gregorian calendar dates with accurate astronomical calculations.
190
    """
191
    
192
    calendar_converter = NotImplemented  # Jalali to Gregorian converter
193
    default_year: int
194
    default_month: int
195
    default_day: int
196

197
class non_gregorian_parser:
198
    """
199
    Base parser class for non-Gregorian calendar systems.
200
    
201
    Provides common functionality for calendar conversion including
202
    digit replacement, month name mapping, and date normalization.
203
    """
204
    
205
    @classmethod
206
    def to_latin(cls, source):
207
        """
208
        Convert non-Latin script to Latin for processing.
209
        
210
        Parameters:
211
        - source (str): Date string in original script
212
        
213
        Returns:
214
        str: Latinized date string for parsing
215
        """
216
    
217
    def handle_two_digit_year(self, year):
218
        """
219
        Handle two-digit year conversion for calendar system.
220
        
221
        Parameters:
222
        - year (int): Two-digit year
223
        
224
        Returns:
225
        int: Full year in calendar system
226
        """
227
```
228

229
**Usage Examples:**
230

231
```python
232
# Using parser classes directly for advanced scenarios
233
from dateparser.calendars.hijri_parser import hijri_parser
234
from dateparser.calendars.jalali_parser import jalali_parser
235
from dateparser.conf import Settings
236

237
# Direct Hijri parsing
238
hijri_text = "15 محرم 1445"
239
latinized = hijri_parser.to_latin(hijri_text)
240
date_obj, period = hijri_parser.parse(latinized, Settings())
241

242
# Direct Jalali parsing  
243
jalali_text = "15 فروردین 1402"
244
latinized = jalali_parser.to_latin(jalali_text)
245
date_obj, period = jalali_parser.parse(latinized, Settings())
246

247
# Custom non-Gregorian parser
248
class MyCalendarParser(non_gregorian_parser):
249
    calendar_converter = MyCalendarConverter()
250
    default_year = 2000
251
    default_month = 1
252
    default_day = 1
253
    
254
    @classmethod
255
    def to_latin(cls, source):
256
        # Custom script conversion
257
        return super().to_latin(source)
258
```
259

260
## Calendar Configuration
261

262
### Installation Requirements
263

264
Calendar systems require additional dependencies for full functionality:
265

266
```python
267
# For Hijri calendar support
268
pip install dateparser[calendars]  # Installs convertdate, hijridate
269

270
# Individual packages
271
pip install convertdate>=2.2.1
272
pip install hijridate
273
```
274

275
### Settings Integration
276

277
```python { .api }
278
# Calendar-specific settings
279
CALENDARS: list  # Enable specific calendar systems ['hijri', 'jalali']
280
```
281

282
**Usage Examples:**
283

284
```python
285
import dateparser
286
from dateparser.conf import Settings
287

288
# Enable multiple calendar systems
289
settings = Settings({
290
    'CALENDARS': ['hijri', 'jalali'],
291
    'DEFAULT_LANGUAGES': ['ar', 'fa', 'en']
292
})
293

294
# Parse dates from different calendar systems
295
hijri_date = dateparser.parse("15 محرم 1445", settings=settings)
296
jalali_date = dateparser.parse("15 فروردین 1402", settings=settings)
297
gregorian_date = dateparser.parse("January 15, 2023", settings=settings)
298

299
# Mixed calendar parsing in text
300
from dateparser.search import search_dates
301

302
text = "Events: 15 محرم 1445 (Hijri), 15 فروردین 1402 (Jalali), January 15, 2023 (Gregorian)"
303
dates = search_dates(text, settings=settings)
304
# Returns dates from all calendar systems converted to Gregorian
305
```