CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-python-dateutil

Extensions to the standard Python datetime module

Pending
Overview
Eval results
Files

relativedelta.mddocs/

Relative Date Calculations

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.

Capabilities

relativedelta Class

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 dates

Weekday Constants

Predefined 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))

Arithmetic Operations

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 2

Usage 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")

Common Patterns

Month-End Date Handling

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 30

Recurring Date Calculations

from 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)]

Types

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 occurrence

Install with Tessl CLI

npx tessl i tessl/pypi-python-dateutil

docs

easter.md

index.md

parser.md

relativedelta.md

rrule.md

tz.md

utils.md

zoneinfo.md

tile.json