Utils#

DateTime utilities for time window generation and date manipulation.

This module provides utilities for generating time windows at various frequencies (hourly, daily, monthly) with optional timezone support. All functions are designed to work with Python 3.12+ without using deprecated datetime methods.

class core_datetime.utils.FrequencyType(*values)[source]#

Bases: Enum

Enumeration of supported time window frequencies

HOUR = 'HOUR'#

MONTH = 'MONTH'#

DAY = 'DAY'#

core_datetime.utils.get_time_windows(start: str, end: str | None = None, frequency: FrequencyType | None = None, tz: timezone | None = None) → Iterator[Tuple[str, str]][source]#

Generate time windows between start and end dates at specified frequency. This function generates tuples of (start_time, end_time) strings representing consecutive time windows based on the specified frequency. If no frequency is provided, returns a single tuple with the start time and current time.

Parameters:

start – ISO format datetime string (e.g., “2022-03-01T10:30:00”). Can be timezone-aware or naive.
end – ISO format datetime string for the end boundary. If None, uses current time. Defaults to None.
frequency – Time window frequency (HOUR, DAY, or MONTH). If None, returns a single window from start to now. Defaults to None.
tz – Timezone to apply to naive datetime strings. If the input strings already contain timezone info, this parameter is ignored for those values. Defaults to None (naive/local time).

Returns:

Iterator of tuples containing (start_time, end_time) strings in ISO format.

HOUR frequency: Returns windows like (“2022-03-01T10:00:00”, “2022-03-01T10:59:59”)
DAY frequency: Returns windows like (“2022-03-01T00:00:00”, “2022-03-01T23:59:59”)
MONTH frequency: Returns windows like (“2022-03-01T00:00:00”, “2022-03-31T23:59:59”)

Examples

>>> # Generate hourly windows for the last 3 hours
>>> start = (datetime.now() - timedelta(hours=3)).isoformat()
>>> for window in get_time_windows(start, frequency=FrequencyType.HOUR):
...     print(window)
('2022-03-01T10:00:00', '2022-03-01T10:59:59')
('2022-03-01T11:00:00', '2022-03-01T11:59:59')
('2022-03-01T12:00:00', '2022-03-01T12:59:59')

>>> # Generate monthly windows with explicit end date
>>> windows = get_time_windows(
...     start="2022-01-01T00:00:00",
...     end="2022-04-01T00:00:00",
...     frequency=FrequencyType.MONTH
... )
>>> list(windows)
[('2022-01-01T00:00:00', '2022-01-31T23:59:59'),
 ('2022-02-01T00:00:00', '2022-02-28T23:59:59'),
 ('2022-03-01T00:00:00', '2022-03-31T23:59:59')]

>>> # Use timezone-aware datetimes
>>> from datetime import timezone
>>> windows = get_time_windows(
...     start="2022-03-01T00:00:00",
...     end="2022-03-02T00:00:00",
...     frequency=FrequencyType.DAY,
...     tz=timezone.utc
... )

Note

Minutes and seconds are normalized to :00:00 for the start time
For HOUR frequency, end times are set to :59:59 of the same hour
For DAY frequency, end times are set to 23:59:59 of the same day
For MONTH frequency, end times are set to 23:59:59 of the last day
Timezone-aware and naive datetimes cannot be mixed; if tz is provided, it will be applied to any naive input strings

Utils#

This Page