0
# python-dateutil
1

2
Powerful extensions to the standard Python datetime module, providing comprehensive functionality for date and time manipulation including relative deltas, date parsing, recurrence rules, timezone handling, and advanced date computations.
3

4
## Package Information
5

6
- **Package Name**: python-dateutil
7
- **Language**: Python
8
- **Installation**: `pip install python-dateutil`
9
- **Documentation**: https://dateutil.readthedocs.io/en/stable/
10

11
## Core Imports
12

13
```python
14
import dateutil
15
```
16

17
Individual module imports:
18

19
```python
20
from dateutil import relativedelta, parser, rrule, tz, easter, utils, zoneinfo
21
```
22

23
## Basic Usage
24

25
```python
26
from dateutil.relativedelta import relativedelta
27
from dateutil.parser import parse
28
from dateutil.tz import gettz
29
from datetime import datetime
30

31
# Relative date calculations
32
now = datetime.now()
33
next_month = now + relativedelta(months=1)
34
next_friday = now + relativedelta(weekday=4)  # Friday
35

36
# Flexible date parsing
37
date1 = parse("2023-12-25")
38
date2 = parse("Dec 25, 2023")
39
date3 = parse("25/12/2023", dayfirst=True)
40

41
# Timezone handling
42
utc = gettz('UTC')
43
eastern = gettz('America/New_York')
44
dt_utc = datetime.now(utc)
45
dt_eastern = dt_utc.astimezone(eastern)
46
```
47

48
## Architecture
49

50
python-dateutil is organized into specialized modules that extend datetime functionality:
51

52
- **relativedelta**: Relative date/time calculations and date component replacement
53
- **parser**: Flexible parsing of date/time strings in various formats
54
- **rrule**: Recurrence rule implementation following iCalendar RFC specification
55
- **tz**: Comprehensive timezone support including system, file-based, and string-based timezones
56
- **easter**: Easter date calculations using various calendar systems
57
- **utils**: General date/time utility functions
58
- **zoneinfo**: Access to bundled timezone database
59

60
## Capabilities
61

62
### Relative Date Calculations
63

64
Advanced date arithmetic supporting relative operations (add/subtract time periods) and absolute operations (set specific date components), with intelligent handling of complex scenarios like month-end dates and weekday calculations.
65

66
```python { .api }
67
class relativedelta:
68
    def __init__(self, dt1=None, dt2=None, years=0, months=0, days=0, 
69
                 leapdays=0, weeks=0, hours=0, minutes=0, seconds=0, 
70
                 microseconds=0, year=None, month=None, day=None, 
71
                 weekday=None, yearday=None, nlyearday=None, hour=None, 
72
                 minute=None, second=None, microsecond=None): ...
73

74
# Weekday constants
75
MO, TU, WE, TH, FR, SA, SU = ...
76
```
77

78
[Relative Date Calculations](./relativedelta.md)
79

80
### Date and Time Parsing
81

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

84
```python { .api }
85
def parse(timestr, parserinfo=None, **kwargs): ...
86
def isoparse(dt_str): ...
87

88
class parser:
89
    def __init__(self, parserinfo=None): ...
90
    def parse(self, timestr, default=None, ignoretz=False, tzinfos=None, **kwargs): ...
91

92
class parserinfo:
93
    def __init__(self, dayfirst=False, yearfirst=False): ...
94
```
95

96
[Date and Time Parsing](./parser.md)
97

98
### Recurrence Rules
99

100
Complete implementation of iCalendar recurrence rules (RFC 5545) for generating recurring dates, with support for complex patterns, exclusions, and efficient iteration over large date ranges.
101

102
```python { .api }
103
class rrule:
104
    def __init__(self, freq, dtstart=None, interval=1, wkst=None, count=None, 
105
                 until=None, bysetpos=None, bymonth=None, bymonthday=None, 
106
                 byyearday=None, byweekno=None, byweekday=None, byhour=None, 
107
                 byminute=None, bysecond=None, cache=False): ...
108

109
class rruleset:
110
    def __init__(self, cache=False): ...
111

112
def rrulestr(s, **kwargs): ...
113

114
# Frequency constants
115
YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY, SECONDLY = ...
116
```
117

118
[Recurrence Rules](./rrule.md)
119

120
### Timezone Support
121

122
Comprehensive timezone handling supporting UTC, fixed offsets, system local timezone, tzfile format, Windows registry timezones, iCalendar timezones, and POSIX TZ strings.
123

124
```python { .api }
125
class tzutc: ...
126
class tzoffset:
127
    def __init__(self, name, offset): ...
128
class tzlocal: ...
129
class tzfile:
130
    def __init__(self, fileobj, filename=None): ...
131

132
def gettz(name=None): ...
133
def enfold(dt, fold=1): ...
134
def datetime_ambiguous(dt, tz=None): ...
135
def datetime_exists(dt, tz=None): ...
136

137
UTC = tzutc()  # Singleton instance
138
```
139

140
[Timezone Support](./tz.md)
141

142
### Easter Date Calculation
143

144
Computation of Easter Sunday dates using Western, Orthodox, and Julian calendar algorithms for any given year.
145

146
```python { .api }
147
def easter(year, method=EASTER_WESTERN): ...
148

149
EASTER_JULIAN = 1
150
EASTER_ORTHODOX = 2
151
EASTER_WESTERN = 3
152
```
153

154
[Easter Date Calculation](./easter.md)
155

156
### Date Utilities
157

158
General convenience functions for common date and time operations including current day calculation, timezone defaulting, and date comparison within tolerance.
159

160
```python { .api }
161
def today(tzinfo=None): ...
162
def default_tzinfo(dt, tzinfo): ...
163
def within_delta(dt1, dt2, delta): ...
164
```
165

166
[Date Utilities](./utils.md)
167

168
### Timezone Database Access
169

170
Access to dateutil's bundled timezone database with metadata support, providing an alternative to system timezone data.
171

172
```python { .api }
173
class ZoneInfoFile:
174
    def __init__(self, zonefile_stream=None): ...
175
    def get(self, name, default=None): ...
176

177
def get_zonefile_instance(new_instance=False): ...
178
```
179

180
[Timezone Database Access](./zoneinfo.md)
181

182
## Common Types
183

184
```python { .api }
185
# From datetime module (used throughout dateutil)
186
class datetime: ...
187
class date: ...
188
class time: ...
189
class timedelta: ...
190
class tzinfo: ...
191

192
# dateutil-specific exceptions
193
class ParserError(ValueError): ...
194
class UnknownTimezoneWarning(RuntimeWarning): ...
195
class DeprecatedTzFormatWarning(Warning): ...
196
```