0
# Core Date Parsing
1

2
Primary date parsing functionality providing the main entry point for converting human-readable date strings into Python datetime objects. Supports automatic language detection, multiple date formats, and extensive localization.
3

4
## Capabilities
5

6
### Main Parse Function
7

8
The primary parsing function that handles most common date parsing scenarios with automatic language detection and format recognition.
9

10
```python { .api }
11
def parse(date_string, date_formats=None, languages=None, locales=None, 
12
          region=None, settings=None, detect_languages_function=None):
13
    """
14
    Parse date and time from given date string.
15

16
    Parameters:
17
    - date_string (str): A string representing date and/or time in a recognizably valid format
18
    - date_formats (list, optional): List of format strings using strftime directives
19
    - languages (list, optional): List of language codes (e.g. ['en', 'es', 'zh-Hant'])  
20
    - locales (list, optional): List of locale codes (e.g. ['fr-PF', 'qu-EC', 'af-NA'])
21
    - region (str, optional): Region code (e.g. 'IN', '001', 'NE')
22
    - settings (dict, optional): Configure customized behavior using Settings
23
    - detect_languages_function (function, optional): Custom language detection function
24
    
25
    Returns:
26
    datetime: Parsed date if successful, else None
27
    
28
    Raises:
29
    ValueError: Unknown Language
30
    TypeError: Languages argument must be a list
31
    SettingValidationError: A provided setting is not valid
32
    """
33
```
34

35
**Usage Examples:**
36

37
```python
38
import dateparser
39

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

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

48
# Relative dates
49
date = dateparser.parse('2 weeks ago')
50
date = dateparser.parse('tomorrow')
51
date = dateparser.parse('next Friday')
52

53
# Custom date formats
54
date = dateparser.parse('2023/01/15', date_formats=['%Y/%m/%d'])
55

56
# With specific locale
57
date = dateparser.parse('15 janvier 2023', locales=['fr-FR'])
58
```
59

60
### Advanced Parser Class
61

62
A configurable parser class for advanced parsing scenarios requiring custom language detection, settings, or reusable parser instances.
63

64
```python { .api }
65
class DateDataParser:
66
    """
67
    Class which handles language detection, translation and subsequent parsing
68
    of string representing date and/or time.
69
    """
70
    
71
    def __init__(self, languages=None, locales=None, region=None, 
72
                 try_previous_locales=False, use_given_order=False, 
73
                 settings=None, detect_languages_function=None):
74
        """
75
        Initialize DateDataParser with custom configuration.
76
        
77
        Parameters:
78
        - languages (list, optional): List of language codes for translation
79
        - locales (list, optional): List of locale codes for translation
80
        - region (str, optional): Region code for locale construction
81
        - try_previous_locales (bool): Try previously used locales first
82
        - use_given_order (bool): Try locales in given order
83
        - settings (dict, optional): Custom parsing settings
84
        - detect_languages_function (function, optional): Custom language detection
85
        
86
        Raises:
87
        ValueError: Unknown Language
88
        TypeError: Languages/locales argument must be a list
89
        SettingValidationError: A provided setting is not valid
90
        """
91
    
92
    def get_date_data(self, date_string, date_formats=None):
93
        """
94
        Parse string representing date and/or time in recognizable localized formats.
95
        
96
        Parameters:
97
        - date_string (str): String to parse
98
        - date_formats (list, optional): List of format strings to try
99
        
100
        Returns:
101
        DateData: Object containing parsed date information and metadata
102
        """
103
    
104
    def get_date_tuple(self, *args, **kwargs):
105
        """
106
        Parse date and return tuple of parsed fields.
107
        
108
        Returns:
109
        tuple: Tuple containing parsed date fields
110
        """
111
```
112

113
**Usage Examples:**
114

115
```python
116
from dateparser import DateDataParser
117

118
# Create parser for specific languages
119
parser = DateDataParser(languages=['en', 'es', 'fr'])
120
date_data = parser.get_date_data('15 enero 2023')
121
date = date_data.date_obj
122
locale = date_data.locale
123

124
# Create parser with custom settings
125
from dateparser.conf import Settings
126
settings = Settings(PREFER_DATES_FROM='future', STRICT_PARSING=True)
127
parser = DateDataParser(settings=settings)
128
date_data = parser.get_date_data('tomorrow')
129

130
# Reuse parser for multiple dates
131
parser = DateDataParser(languages=['de'], region='DE')
132
dates = []
133
for date_string in ['1. Januar 2023', '15. März 2023', 'gestern']:
134
    date_data = parser.get_date_data(date_string)
135
    if date_data:
136
        dates.append(date_data.date_obj)
137
```
138

139
### Specialized Parsing Functions
140

141
Lower-level parsing functions for specific date formats and edge cases.
142

143
```python { .api }
144
def get_date_from_timestamp(date_string, settings, negative=False):
145
    """
146
    Convert timestamp string to datetime object.
147
    
148
    Parameters:
149
    - date_string (str): Timestamp string to parse
150
    - settings (Settings): Parsing settings
151
    - negative (bool): Whether to handle negative timestamps
152
    
153
    Returns:
154
    datetime: Parsed datetime from timestamp
155
    """
156

157
def parse_with_formats(date_string, date_formats, settings):
158
    """
159
    Parse using provided format strings.
160
    
161
    Parameters:
162
    - date_string (str): String to parse
163
    - date_formats (list): List of strftime format strings
164
    - settings (Settings): Parsing settings
165
    
166
    Returns:
167
    datetime: Parsed datetime object
168
    """
169

170
def sanitize_date(date_string):
171
    """
172
    Sanitize and normalize date strings.
173
    
174
    Parameters:
175
    - date_string (str): String to sanitize
176
    
177
    Returns:
178
    str: Cleaned date string
179
    """
180
```
181

182
## Types
183

184
```python { .api }
185
class DateData:
186
    """Container for parsed date information and metadata."""
187
    
188
    def __init__(self, date_obj=None, period=None, locale=None):
189
        """
190
        Initialize DateData container.
191
        
192
        Parameters:
193
        - date_obj (datetime, optional): Parsed datetime object
194
        - period (str, optional): Time period information
195
        - locale (Locale, optional): Detected locale used for parsing
196
        """
197
    
198
    date_obj: datetime  # The parsed datetime object
199
    period: str         # Time period information (e.g., 'day', 'week')
200
    locale: Locale      # Locale used for parsing
201
```