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