Extensions to the standard Python datetime module
—
Advanced date arithmetic supporting both relative operations (add/subtract time periods) and absolute operations (set specific date components). Handles complex scenarios like month-end dates, leap years, and weekday calculations intelligently.
The core class for relative date calculations, supporting both relative and absolute date operations in a single interface.
class relativedelta:
def __init__(self, dt1=None, dt2=None,
years=0, months=0, days=0, leapdays=0, weeks=0,
hours=0, minutes=0, seconds=0, microseconds=0,
year=None, month=None, day=None, weekday=None,
yearday=None, nlyearday=None,
hour=None, minute=None, second=None, microsecond=None):
"""
Create a relativedelta instance for date calculations.
Parameters:
- dt1, dt2 (datetime, optional): Create relativedelta from difference between two datetimes
- Relative parameters (plural): years, months, days, weeks, hours, minutes, seconds, microseconds, leapdays
- Absolute parameters (singular): year, month, day, hour, minute, second, microsecond
- weekday (weekday instance): Weekday specification (MO, TU, etc.)
- yearday (int): Day of year (1-366)
- nlyearday (int): Day of non-leap year (1-365)
"""
def normalized(self):
"""
Return a relativedelta with normalized relative components.
Returns:
relativedelta: New instance with integer relative attributes
"""
@property
def weeks(self):
"""Get/set weeks property."""Usage Examples:
from dateutil.relativedelta import relativedelta
from datetime import datetime
# Relative operations (add/subtract)
dt = datetime(2023, 1, 31)
next_month = dt + relativedelta(months=1) # Feb 28, 2023
next_year = dt + relativedelta(years=1) # Jan 31, 2024
# Absolute operations (replace)
new_year = dt + relativedelta(month=1, day=1) # Jan 1, 2023
midnight = dt + relativedelta(hour=0, minute=0, second=0)
# Mixed operations
first_friday = dt + relativedelta(day=1, weekday=4) # First Friday of month
# From two datetimes
dt1 = datetime(2023, 12, 25)
dt2 = datetime(2024, 1, 15)
delta = relativedelta(dt2, dt1) # Difference between datesPredefined weekday instances for use in relativedelta calculations, supporting nth weekday specifications.
# Weekday constants (Monday=0 to Sunday=6)
MO = weekday(0)
TU = weekday(1)
WE = weekday(2)
TH = weekday(3)
FR = weekday(4)
SA = weekday(5)
SU = weekday(6)
class weekday:
def __init__(self, wkday, n=None):
"""
Weekday specification for relativedelta.
Parameters:
- wkday (int): Weekday number (0=Monday, 6=Sunday)
- n (int, optional): Nth occurrence (+1 for next, -1 for previous)
"""Usage Examples:
from dateutil.relativedelta import relativedelta, MO, FR
from datetime import datetime
dt = datetime(2023, 6, 15) # Thursday
# Next Friday
next_fri = dt + relativedelta(weekday=FR) # June 16, 2023
next_fri_2 = dt + relativedelta(weekday=FR(1)) # Same as above
# Previous Friday
prev_fri = dt + relativedelta(weekday=FR(-1)) # June 9, 2023
# First Monday of next month
first_mon = dt + relativedelta(months=1, day=1, weekday=MO)
# Last Friday of current month
last_fri = dt + relativedelta(day=31, weekday=FR(-1))relativedelta supports all standard arithmetic operations for combining and manipulating date deltas.
# Addition and subtraction
def __add__(self, other): ... # relativedelta + datetime/relativedelta
def __radd__(self, other): ... # datetime + relativedelta
def __sub__(self, other): ... # relativedelta - relativedelta
def __rsub__(self, other): ... # datetime - relativedelta
# Multiplication and division
def __mul__(self, other): ... # relativedelta * number
def __rmul__(self, other): ... # number * relativedelta
def __div__(self, other): ... # relativedelta / number (Python 2)
def __truediv__(self, other): ... # relativedelta / number (Python 3)
# Unary operations
def __neg__(self): ... # -relativedelta
def __abs__(self): ... # abs(relativedelta)
# Comparison operations
def __eq__(self, other): ... # relativedelta == relativedelta
def __ne__(self, other): ... # relativedelta != relativedelta
def __hash__(self): ... # hash(relativedelta)
# Boolean operations
def __bool__(self): ... # bool(relativedelta) - Python 3
def __nonzero__(self): ... # bool(relativedelta) - Python 2Usage Examples:
from dateutil.relativedelta import relativedelta
from datetime import datetime
# Combining relativedeltas
delta1 = relativedelta(months=1, days=5)
delta2 = relativedelta(weeks=2, hours=3)
combined = delta1 + delta2
# Multiplying deltas
double_delta = delta1 * 2
half_delta = delta1 / 2
# Boolean testing
if delta1: # True if any non-zero components
print("Delta has non-zero components")
# Comparison
if delta1 == delta2:
print("Deltas are equal")from dateutil.relativedelta import relativedelta
from datetime import datetime
# Safe month arithmetic for month-end dates
jan_31 = datetime(2023, 1, 31)
feb_end = jan_31 + relativedelta(months=1) # Feb 28, 2023 (not March 3rd)
mar_end = feb_end + relativedelta(months=1) # Mar 28, 2023
# Get last day of month
last_day = datetime(2023, 6, 1) + relativedelta(months=1, days=-1) # June 30from dateutil.relativedelta import relativedelta, MO
from datetime import datetime
start_date = datetime(2023, 1, 1)
# Every 3rd Monday of each month for a year
third_mondays = []
for month in range(12):
third_monday = start_date + relativedelta(months=month, day=1, weekday=MO(3))
third_mondays.append(third_monday)
# Quarterly dates
quarterly = [start_date + relativedelta(months=3*i) for i in range(4)]class relativedelta:
# Instance attributes (read-only after construction)
years: int
months: int
days: int
leapdays: int
hours: int
minutes: int
seconds: int
microseconds: int
year: int | None
month: int | None
day: int | None
weekday: weekday | None
hour: int | None
minute: int | None
second: int | None
microsecond: int | None
class weekday:
weekday: int # 0-6 (Monday-Sunday)
n: int | None # Nth occurrenceInstall with Tessl CLI
npx tessl i tessl/pypi-python-dateutil