0
# Date and Time Parsing
1

2
Flexible parsing of date and time strings in almost any format, with support for ambiguous date resolution, timezone parsing, fuzzy parsing, and high-performance ISO-8601 parsing.
3

4
## Capabilities
5

6
### Main Parsing Function
7

8
The primary entry point for parsing date/time strings with extensive configuration options.
9

10
```python { .api }
11
def parse(timestr, parserinfo=None, **kwargs):
12
    """
13
    Parse a date/time string into a datetime object.
14
    
15
    Parameters:
16
    - timestr (str): String containing date and/or time
17
    - parserinfo (parserinfo, optional): Parser configuration object
18
    - default (datetime, optional): Default datetime for missing components
19
    - ignoretz (bool): If True, ignore timezone info and return naive datetime
20
    - tzinfos (dict/callable, optional): Additional timezone name mappings
21
    - dayfirst (bool): Interpret ambiguous dates as day-first (DD/MM/YYYY)
22
    - yearfirst (bool): Interpret ambiguous dates as year-first (YYYY/MM/DD)  
23
    - fuzzy (bool): Ignore unknown tokens in the string
24
    - fuzzy_with_tokens (bool): Return (datetime, tokens) tuple with unknown tokens
25
    
26
    Returns:
27
    datetime: Parsed datetime object
28
    
29
    Raises:
30
    ParserError: When string cannot be parsed
31
    """
32

33
class ParserError(ValueError):
34
    """Raised when a date/time string cannot be parsed."""
35
```
36

37
**Usage Examples:**
38

39
```python
40
from dateutil.parser import parse
41
from datetime import datetime
42

43
# Basic parsing - various formats
44
dt1 = parse("2023-12-25")                    # ISO format
45
dt2 = parse("Dec 25, 2023")                  # Named month
46
dt3 = parse("25/12/2023")                    # Ambiguous format
47
dt4 = parse("2023-12-25T14:30:00Z")          # ISO with timezone
48

49
# Ambiguous date resolution
50
parse("12/25/2023")                          # Assumes MM/DD/YYYY (US)
51
parse("12/25/2023", dayfirst=True)           # Forces DD/MM/YYYY (EU)
52
parse("2023/12/25", yearfirst=True)          # YYYY/MM/DD format
53

54
# Default values for missing components
55
default = datetime(2023, 1, 1, 9, 0, 0)
56
parse("Dec 25", default=default)             # Uses year/time from default
57

58
# Timezone handling
59
parse("2023-12-25 14:30 EST")                # With timezone name
60
parse("2023-12-25 14:30 +0500")             # With offset
61
parse("2023-12-25 14:30 EST", ignoretz=True) # Ignore timezone
62

63
# Fuzzy parsing
64
parse("Today is Dec 25, 2023", fuzzy=True)   # Extracts date from text
65
dt, tokens = parse("Event on Dec 25, 2023 at venue", fuzzy_with_tokens=True)
66
```
67

68
### ISO-8601 Fast Parser
69

70
High-performance parser specifically optimized for ISO-8601 formatted strings.
71

72
```python { .api }
73
def isoparse(dt_str):
74
    """
75
    Parse ISO-8601 formatted date/time strings.
76
    
77
    Parameters:
78
    - dt_str (str): ISO-8601 formatted string
79
    
80
    Returns:
81
    datetime: Parsed datetime object
82
    
83
    Raises:
84
    ValueError: When string is not valid ISO-8601 format
85
    """
86

87
class isoparser:
88
    def __init__(self, sep=None):
89
        """
90
        ISO-8601 parser with configurable date/time separator.
91
        
92
        Parameters:
93
        - sep (str, optional): Custom separator between date and time parts
94
        """
95
        
96
    def isoparse(self, dt_str):
97
        """Parse ISO-8601 string using this parser instance."""
98
```
99

100
**Usage Examples:**
101

102
```python
103
from dateutil.parser import isoparse, isoparser
104

105
# Standard ISO-8601 formats
106
dt1 = isoparse("2023-12-25")                 # Date only
107
dt2 = isoparse("2023-12-25T14:30:00")        # Date and time
108
dt3 = isoparse("2023-12-25T14:30:00Z")       # With UTC timezone
109
dt4 = isoparse("2023-12-25T14:30:00+05:00")  # With offset timezone
110
dt5 = isoparse("2023-12-25 14:30:00")        # Space separator
111

112
# Custom parser with different separator
113
parser = isoparser(sep='_')
114
dt = parser.isoparse("2023-12-25_14:30:00")
115
```
116

117
### Module Constants
118

119
Pre-configured parser instances available for direct use.
120

121
```python { .api }
122
DEFAULTPARSER: parser
123
    """Default parser instance used by module-level parse() function."""
124

125
DEFAULTTZPARSER: parser  
126
    """Default timezone-aware parser instance for internal use."""
127
```
128

129
### Parser Configuration
130

131
Configurable parser class for customizing parsing behavior and locale settings.
132

133
```python { .api }
134
class parser:
135
    def __init__(self, parserinfo=None):
136
        """
137
        Create a parser with custom configuration.
138
        
139
        Parameters:
140
        - parserinfo (parserinfo, optional): Parser configuration object
141
        """
142
        
143
    def parse(self, timestr, default=None, ignoretz=False, tzinfos=None, **kwargs):
144
        """
145
        Parse date/time string using this parser's configuration.
146
        
147
        Parameters: Same as module-level parse() function
148
        Returns: datetime object
149
        """
150

151
class parserinfo:
152
    def __init__(self, dayfirst=False, yearfirst=False):
153
        """
154
        Parser configuration for locale-specific parsing.
155
        
156
        Parameters:
157
        - dayfirst (bool): Default day-first interpretation
158
        - yearfirst (bool): Default year-first interpretation
159
        """
160
        
161
    # Configuration attributes
162
    JUMP: list[str]        # Words to ignore ("at", "on", "the")
163
    WEEKDAYS: list[list[str]]  # Weekday names by language
164
    MONTHS: list[list[str]]    # Month names by language  
165
    HMS: list[list[str]]       # Hour/minute/second indicators
166
    AMPM: list[str]           # AM/PM indicators
167
    UTCZONE: list[str]        # UTC timezone names
168
    PERTAIN: list[str]        # Pertaining words ("of", "in")
169
```
170

171
**Usage Examples:**
172

173
```python
174
from dateutil.parser import parser, parserinfo
175

176
# Custom parser info for different locale
177
class CustomParserInfo(parserinfo):
178
    MONTHS = [
179
        ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
180
         "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
181
        ["Januar", "Februar", "März", "April", "Mai", "Juni",
182
         "Juli", "August", "September", "Oktober", "November", "Dezember"]
183
    ]
184

185
custom_parser = parser(CustomParserInfo())
186
dt = custom_parser.parse("25 März 2023")  # German month name
187

188
# Parser with default settings
189
eu_parser = parser(parserinfo(dayfirst=True))
190
us_parser = parser(parserinfo(dayfirst=False))
191

192
dt_eu = eu_parser.parse("12/03/2023")  # March 12, 2023
193
dt_us = us_parser.parse("12/03/2023")  # December 3, 2023
194
```
195

196
### Timezone Information Handling
197

198
Support for custom timezone mappings and resolution.
199

200
```python { .api }
201
class UnknownTimezoneWarning(RuntimeWarning):
202
    """Warning issued when encountering unknown timezone names."""
203

204
# Timezone resolution in parse() function
205
def parse(timestr, tzinfos=None, **kwargs):
206
    """
207
    tzinfos parameter options:
208
    - dict: Mapping of timezone names to tzinfo objects
209
    - callable: Function that takes timezone name and returns tzinfo object
210
    """
211
```
212

213
**Usage Examples:**
214

215
```python
216
from dateutil.parser import parse
217
from dateutil.tz import gettz
218

219
# Custom timezone mappings
220
custom_timezones = {
221
    'EST': gettz('America/New_York'),
222
    'PST': gettz('America/Los_Angeles'),
223
    'JST': gettz('Asia/Tokyo')
224
}
225

226
dt = parse("2023-12-25 14:30 JST", tzinfos=custom_timezones)
227

228
# Dynamic timezone resolution
229
def resolve_timezone(tzname):
230
    """Custom timezone resolver function."""
231
    timezone_map = {
232
        'ET': 'America/New_York',
233
        'PT': 'America/Los_Angeles',
234
        'MT': 'America/Denver'
235
    }
236
    if tzname in timezone_map:
237
        return gettz(timezone_map[tzname])
238
    return None
239

240
dt = parse("2023-12-25 14:30 ET", tzinfos=resolve_timezone)
241
```
242

243
## Advanced Parsing Patterns
244

245
### Fuzzy Parsing with Token Extraction
246

247
```python
248
from dateutil.parser import parse
249

250
text = "Meeting scheduled for December 25th, 2023 at the main office"
251
dt, tokens = parse(text, fuzzy_with_tokens=True)
252
print(f"Date: {dt}")
253
print(f"Ignored tokens: {tokens}")  # ['Meeting', 'scheduled', 'for', 'at', 'the', 'main', 'office']
254
```
255

256
### Handling Multiple Date Formats
257

258
```python
259
from dateutil.parser import parse, ParserError
260

261
date_strings = [
262
    "2023-12-25",
263
    "Dec 25, 2023", 
264
    "25/12/2023",
265
    "invalid date"
266
]
267

268
parsed_dates = []
269
for date_str in date_strings:
270
    try:
271
        dt = parse(date_str, dayfirst=True)
272
        parsed_dates.append(dt)
273
    except ParserError:
274
        print(f"Could not parse: {date_str}")
275
```
276

277
### Performance Considerations
278

279
```python
280
from dateutil.parser import parse, isoparse
281

282
# For ISO-8601 strings, isoparse is much faster
283
iso_string = "2023-12-25T14:30:00Z"
284
dt_fast = isoparse(iso_string)      # Faster
285
dt_slow = parse(iso_string)         # Slower but more flexible
286

287
# For non-ISO strings, use parse
288
natural_string = "Dec 25, 2023 2:30 PM"
289
dt = parse(natural_string)  # Only option
290
```
291

292
## Types
293

294
```python { .api }
295
# Standard datetime types (from datetime module)
296
from datetime import datetime, tzinfo
297

298
# Parser-specific exceptions
299
class ParserError(ValueError):
300
    """Exception raised when parsing fails."""
301

302
class UnknownTimezoneWarning(RuntimeWarning):
303
    """Warning for unknown timezone names."""
304

305
# Parser configuration types
306
class parserinfo:
307
    JUMP: list[str]
308
    WEEKDAYS: list[list[str]]
309
    MONTHS: list[list[str]]
310
    HMS: list[list[str]]
311
    AMPM: list[str] 
312
    UTCZONE: list[str]
313
    PERTAIN: list[str]
314

315
# Timezone info parameter types
316
TzInfos = dict[str, tzinfo] | callable[[str], tzinfo | None] | None
317
```