Skip to content

Date time

Utility functions related to date and time operations

koheesio.utils.date_time.extract_dt_interval module-attribute #

extract_dt_interval = compile(
    "\n    (?P<years>\\d+)\\s+years?\\s*|\n    (?P<months>\\d+)\\s+months?\\s*|\n    (?P<weeks>\\d+)\\s+weeks?\\s*|\n    (?P<days>\\d+)\\s+days?\\s*|\n    (?P<hours>\\d+)\\s+hours?\\s*|\n    (?P<minutes>\\d+)\\s+(?:minutes?|mins?)\\s*|\n    (?P<seconds>\\d+)\\s+(?:seconds?|secs?)\\s*|\n    (?P<milliseconds>\\d+)\\s+(?:milliseconds?|millis?)\\s*|\n    (?P<microseconds>\\d+)\\s+(?:microseconds?|micros?)\\s*\n",
    VERBOSE,
)

koheesio.utils.date_time.DTInterval #

A class to define date and time intervals using human-readable strings or individual time components.

Parameters:

Name Type Description Default
interval str

A human-readable string specifying the duration of the interval, broken down into years, months, weeks, days, hours, minutes, seconds, milliseconds, and microseconds.

required
years int

Number of years in the interval.

0
months int

Number of months in the interval.

0
weeks int

Number of weeks in the interval.

0
days int

Number of days in the interval.

0
hours int

Number of hours in the interval.

0
minutes int

Number of minutes in the interval.

0
seconds int

Number of seconds in the interval.

0
milliseconds int

Number of milliseconds in the interval.

0
microseconds int

Number of microseconds in the interval.

0

Examples:

Creating an instance with time components:

print(DTInterval(years=2, weeks=3, hours=12).to_timedelta)
751 days, 12:00:00

Creating an instance from a string:

print(
    DTInterval(
        interval="1 year 2 months 3 weeks 4 days 5 hours 100 minutes 200 seconds 300 milliseconds 400 microseconds"
    ).to_timedelta
)
451 days, 6:43:20.300400

Methods:

Name Description
to_timedelta

Converts the DTInterval instance to a timedelta object, aggregating all specified time components.

days class-attribute instance-attribute #

days: Optional[int] = 0

hours class-attribute instance-attribute #

hours: Optional[int] = 0

interval class-attribute instance-attribute #

interval: Optional[str] = None

microseconds class-attribute instance-attribute #

microseconds: Optional[int] = 0

milliseconds class-attribute instance-attribute #

milliseconds: Optional[int] = 0

minutes class-attribute instance-attribute #

minutes: Optional[int] = 0

months class-attribute instance-attribute #

months: Optional[int] = 0

seconds class-attribute instance-attribute #

seconds: Optional[int] = 0

to_timedelta property #

to_timedelta: timedelta

Returns the object as a timedelta object

weeks class-attribute instance-attribute #

weeks: Optional[int] = 0

years class-attribute instance-attribute #

years: Optional[int] = 0

calculate_days #

calculate_days() -> DTInterval

Years and months are not supported in timedelta, so we need to convert them to days

Source code in src/koheesio/utils/date_time.py
@model_validator(mode="after")
def calculate_days(self) -> "DTInterval":
    """Years and months are not supported in timedelta, so we need to convert them to days"""
    if self.years or self.months:
        year_month_days = int(self.years * 365.25 + self.months * 30.44)  # average year length
        self.days += year_month_days
        self.years = 0
        self.months = 0
    return self

process_interval #

process_interval(values: dict) -> dict

Processes the input interval string and extracts the time components

Source code in src/koheesio/utils/date_time.py
@model_validator(mode="before")
def process_interval(cls, values: dict) -> dict:
    """Processes the input interval string and extracts the time components"""
    if interval_value := values.get("interval"):
        matches = extract_dt_interval.finditer(interval_value)

        # update values with the extracted values
        for match in matches:
            for key, value in match.groupdict().items():
                if value:
                    values[key] = int(value)
    return values