0
# Dateparser
1

2
A comprehensive Python library for parsing human-readable dates in multiple formats and languages. Dateparser supports almost every existing date format including absolute dates, relative dates (like 'two weeks ago' or 'tomorrow'), timestamps, and dates from HTML pages. The library handles over 200 language locales, making it suitable for international applications that need to process dates from various cultural contexts.
3

4
## Package Information
5

6
- **Package Name**: dateparser
7
- **Language**: Python  
8
- **Installation**: `pip install dateparser`
9
- **Version**: 1.2.2
10

11
## Core Imports
12

13
```python
14
import dateparser
15
```
16

17
For parsing individual dates:
18

19
```python  
20
from dateparser import parse
21
from dateparser import DateDataParser
22
```
23

24
For searching dates in text:
25

26
```python
27
from dateparser.search import search_dates
28
```
29

30
For configuration:
31

32
```python
33
from dateparser.conf import Settings
34
```
35

36
## Basic Usage
37

38
```python
39
import dateparser
40

41
# Basic date parsing
42
date = dateparser.parse('2023-01-15')
43
# Returns: datetime.datetime(2023, 1, 15, 0, 0)
44

45
# Multi-language support
46
date = dateparser.parse('15 de enero de 2023', languages=['es'])
47
# Returns: datetime.datetime(2023, 1, 15, 0, 0)
48

49
# Relative date parsing
50
date = dateparser.parse('2 weeks ago')
51
# Returns: datetime corresponding to 2 weeks before current date
52

53
# Search for dates in text
54
from dateparser.search import search_dates
55
text = "The event happened on January 15, 2023 and ended on Feb 20, 2023"
56
dates = search_dates(text)
57
# Returns: [('January 15, 2023', datetime.datetime(2023, 1, 15, 0, 0)), 
58
#           ('Feb 20, 2023', datetime.datetime(2023, 2, 20, 0, 0))]
59

60
# Custom configuration
61
from dateparser.conf import Settings
62
settings = Settings(PREFER_DATES_FROM='future', TIMEZONE='UTC')
63
date = dateparser.parse('tomorrow', settings=settings)
64
```
65

66
## Architecture
67

68
Dateparser uses a modular architecture built around several key components:
69

70
- **Parser Core**: `DateDataParser` class handles language detection, translation, and parsing
71
- **Search Module**: `search_dates` function finds and parses dates within text
72
- **Language Support**: Automatic language detection with support for 200+ locales
73
- **Calendar Systems**: Support for non-Gregorian calendars (Hijri, Jalali)
74
- **Settings System**: Comprehensive configuration for parsing behavior
75
- **Timezone Handling**: Built-in timezone parsing and conversion support
76

77
## Capabilities
78

79
### Core Date Parsing
80

81
Primary date parsing functionality including the main `parse()` function and the configurable `DateDataParser` class for advanced parsing scenarios with language detection and custom settings.
82

83
```python { .api }
84
def parse(date_string, date_formats=None, languages=None, locales=None, 
85
          region=None, settings=None, detect_languages_function=None):
86
    """Parse date and time from given date string."""
87

88
class DateDataParser:
89
    """Handles language detection, translation and parsing of date strings."""
90
    def __init__(self, languages=None, locales=None, region=None, 
91
                 try_previous_locales=False, use_given_order=False, 
92
                 settings=None, detect_languages_function=None): ...
93
    def get_date_data(self, date_string, date_formats=None): ...
94
```
95

96
[Core Date Parsing](./core-parsing.md)
97

98
### Date Search in Text
99

100
Search functionality for finding and parsing multiple dates within text documents, with automatic language detection and customizable settings for batch date extraction.
101

102
```python { .api }
103
def search_dates(text, languages=None, settings=None, 
104
                 add_detected_language=False, detect_languages_function=None):
105
    """Find all substrings representing date and/or time and parse them."""
106
```
107

108
[Date Search](./date-search.md)
109

110
### Configuration and Settings
111

112
Comprehensive configuration system for customizing parsing behavior including date order preferences, timezone handling, language detection, and parsing strategies.
113

114
```python { .api }
115
class Settings:
116
    """Control and configure default parsing behavior."""
117
    def __init__(self, settings=None): ...
118
    def replace(self, mod_settings=None, **kwds): ...
119

120
class SettingValidationError(ValueError):
121
    """Raised when a provided setting is not valid."""
122

123
class UnknownTokenError(Exception):
124
    """Raised when an unknown token is encountered during parsing."""
125
```
126

127
[Configuration](./configuration.md)
128

129
### Calendar Systems
130

131
Support for non-Gregorian calendar systems including Islamic (Hijri) and Persian (Jalali) calendars for parsing dates in different cultural contexts.
132

133
```python { .api }
134
class HijriCalendar(CalendarBase):
135
    """Support for Hijri (Islamic) calendar dates."""
136
    
137
class JalaliCalendar(CalendarBase):
138
    """Support for Jalali (Persian) calendar dates."""
139
```
140

141
[Calendar Systems](./calendar-systems.md)
142

143
### Utility Functions
144

145
Additional utility functions for date manipulation, timezone handling, and date range generation to support complex date processing workflows.
146

147
```python { .api }
148
def date_range(begin, end, **kwargs):
149
    """Generate sequence of dates between begin and end."""
150

151
def get_intersecting_periods(low, high, period="day"):
152
    """Get periods that intersect with given range."""
153
```
154

155
[Utilities](./utilities.md)
156

157
## Types
158

159
```python { .api }
160
class DateData:
161
    """Container for parsed date information."""
162
    def __init__(self, date_obj=None, period=None, locale=None): ...
163
    date_obj: datetime
164
    period: str
165
    locale: Locale
166

167
class CalendarBase:
168
    """Base setup class for non-Gregorian calendar system."""
169
    def __init__(self, source: str): ...
170
    def get_date(self) -> DateData: ...
171

172
class Locale:
173
    """Class that deals with applicability and translation from a locale."""
174
    def __init__(self, shortname: str, language_info: dict): ...
175
    shortname: str
176
    language_info: dict
177
```