akkudoktoreos.utils.datetimeutil

Utility module for date, time, and timezone handling.

This module provides a unified interface for working with dates, times, durations, and timezones. It leverages the pendulum library to simplify conversions between string representations, native datetime/date/timedelta types, Unix timestamps, and timezone-aware types.

Features:

  • Parse and normalize various date or timestamp formats into a pendulum.DateTime.

  • Convert durations from strings or numerics into pendulum.Duration.

  • Infer timezone from UTC offset or geolocation.

  • Support for custom output formats (ISO 8601, UTC normalized, or user-specified formats).

  • Makes pendulum types usable in pydantic models using pydantic_extra_types.pendulum_dt and the Time class.

Types:

  • Time: Pendulum’s time type with timezone awareness.

  • DateTime: Pendulum’s timezone-aware datetime type.

  • Date: Pendulum’s date type.

  • Duration: Pendulum’s representation of a time delta.

  • TimeWindow: Daily or specific date time window with optional localization support.

Functions:

  • to_time: Convert diverse time inputs into a Time or formatted string.

  • to_datetime: Convert diverse date/time inputs into a DateTime or formatted string.

  • to_duration: Convert strings or numerics into a Duration.

  • to_timezone: Convert a UTC offset or geographic coordinate into a Timezone or its name.

Usage Examples:

>>> to_time("15:30:00", in_timezone="Europe/Berlin")
Time(17, 30, 0, tzinfo=Timezone('Europe/Berlin'))

>>> to_datetime("2024-10-13T15:30:00", in_timezone="Europe/Berlin")
DateTime(2024, 10, 13, 17, 30, 0, tzinfo=Timezone('Europe/Berlin'))

>>> to_duration("2 days 5 hours")
Duration(days=2, hours=5)

>>> to_timezone(location=(40.7128, -74.0060), as_string=True)
'America/New_York'

See each function’s docstring for detailed argument options and examples.

Functions

compare_datetimes(dt1, dt2[, tolerance])

Compares two Pendulum DateTime objects with precision, including DST and timezones.

hours_in_day([dt])

Returns the number of hours in the given date's day, considering DST transitions.

to_datetime()

Convert a date input into a Pendulum DateTime object or a formatted string, with optional timezone handling.

to_duration(input_value)

Converts various input types into a Duration object using pendulum.

to_time()

Convert a time-like value into a timezone-aware Time object or formatted string.

to_timezone()

Determines the timezone either by UTC offset, geographic location, or local system timezone.

Classes

DatetimesComparisonResult(equal, ...)

Encapsulates the result of comparing two Pendulum DateTime objects.

Time(*args[, tzinfo])

A timezone-aware Time class derived from pendulum.Time.

TimeWindow(*, start_time, duration[, ...])

Model defining a daily or specific date time window with optional localization support.

TimeWindowSequence(*, windows)

Model representing a sequence of time windows with collective operations.