antimatter.utils.time#

Module Contents#

Functions#

get_time_range(→ Tuple[Optional[datetime.datetime], ...)

Build a time range from the provided start date, end date, and duration.

normalize_datetime(→ Optional[datetime.datetime])

Normalize the datetime, either ensuring the datetime object has a timezone

parse_datetime(→ datetime.datetime)

Parse the datetime from a string using the dateutil parser. Default date

normalize_duration(...)

Normalize the duration into a relativedelta. This supports relativedelta,

parse_duration(...)

Parse the duration from a string.

Attributes#

microsecond

millisecond

second

minute

hour

day

month

year

antimatter.utils.time.microsecond = 1#
antimatter.utils.time.millisecond#
antimatter.utils.time.second#
antimatter.utils.time.minute#
antimatter.utils.time.hour#
antimatter.utils.time.day#
antimatter.utils.time.month#
antimatter.utils.time.year#
antimatter.utils.time.get_time_range(start_date: datetime.datetime | str | None, end_date: datetime.datetime | str | None, duration: datetime.timedelta | dateutil.relativedelta.relativedelta | str | None) → Tuple[datetime.datetime | None, datetime.datetime | None]#

Build a time range from the provided start date, end date, and duration. Start and end dates can be a datetime or a string representing a date. The duration can be a timedelta, a relativedelta from the dateutil library, or a string representing a span of time, such as 1d5h12m (1 day, 5 hours, 12 minutes) where y (year), mo (month), d (day), h (hour), m (minute), s (second), ms (millisecond), and us/µs (microsecond) are all supported units of time.

There are several combinations of parameters that can be provided, and a start and end date matching the parameters will be returned. The expectation is that the caller treats a None start date as ‘the beginning of time’ and a None end date as ‘now’.

Note that the returned start date and end date will always be timezone aware. If no timezone information is provided, the system timezone will be used.

1. Input: start_date, end_date, duration are all None Output: None will be returned for the start and end date

2. Input: start_date, end_date, duration all have values Output: start_date and end_date will be returned as is, and duration ignored

3. Input: start_date and end_date None; duration has a value Output: start_date will be ‘now’ minus duration; end_date will be None

4. Input: start_date None; end_date and duration have values Output: start_date will be end_date minus duration; end_date will be returned as is

5. Input: end_date None; start_date and duration have values Output: start_date will be returned as is; end_date will be start_date plus duration

Parameters:

  • start_date – The optional provided start date as a datetime or string

  • end_date – The optional provided end date as a datetime or string

  • duration – The optional provided duration as a timedelta, relativedelta, or string

Returns:

The processed start and end dates based on the inputs

antimatter.utils.time.normalize_datetime(dt: datetime.datetime | str | None) → datetime.datetime | None#

Normalize the datetime, either ensuring the datetime object has a timezone or parsing the datetime string.

Parameters:

dt – The datetime as a string or object

Returns:

The parsed, normalized datetime

antimatter.utils.time.parse_datetime(dt: str, default: datetime.datetime | None = None) → datetime.datetime#

Parse the datetime from a string using the dateutil parser. Default date is 1900-01-01T00:00:00.000000 at local timezone, unless otherwise specified.

Parameters:

  • dt – The string to parse as a datetime

  • default – The default datetime to use for filling in missing details

Returns:

The parsed datetime

antimatter.utils.time.normalize_duration(duration: datetime.timedelta | dateutil.relativedelta.relativedelta | str | None) → dateutil.relativedelta.relativedelta | None#

Normalize the duration into a relativedelta. This supports relativedelta, timedelta, and duration strings.

Parameters:

duration – The duration span

Returns:

The normalized duration span

antimatter.utils.time.parse_duration(duration: str | None) → dateutil.relativedelta.relativedelta | None#

Parse the duration from a string.

Parameters:

duration – The duration span string

Returns:

The parsed relativedelta