timefmt._helpers

Helper functions to aid with formatting time-based objects into human-readable text.

Module Contents

Classes

SplitTime

Data class for holding split time values.

Functions

split_seconds(→ SplitTime)	Split seconds into parts ranging from weeks to milliseconds and return a SplitTime object with those values.
day_of_month_suffix(→ str)	Return the appropriate suffix for a specified day of the month.
day_of_month_string(→ str)	Convert a numerical day of the month to a user-friendly string.
timezone_name(→ str)	Get the full timezone name from a datetime.datetime object.

class timefmt._helpers.SplitTime

Data class for holding split time values.

weeks: int

days: int

hours: int

minutes: int

seconds: int

milliseconds: int | float

timefmt._helpers.split_seconds(seconds_in: int | float) → SplitTime

Split seconds into parts ranging from weeks to milliseconds and return a SplitTime object with those values.

Parameters:

seconds_in (int) – The total number of seconds to split up.

Raises:

ValidationError – Raised when a parameter is invalid.

Returns:

A SplitTime object with the split weeks, days, hours, minutes, seconds, and milliseconds.

Return type:

SplitTime

Example:

>>> split_seconds(1.234)
SplitTime(weeks=0, days=0, hours=0, minutes=0, seconds=1, milliseconds=234.0)
>>> split_seconds(123456789)
SplitTime(weeks=204, days=0, hours=21, minutes=33, seconds=9, milliseconds=0)
>>> split_seconds(-3)
Traceback (most recent call last):
    ...
onecondition.ValidationError: Value `-3` must not be negative (non-zero)

timefmt._helpers.day_of_month_suffix(day: int) → str

Return the appropriate suffix for a specified day of the month.

Parameters:

day (int) – The day of the month to get the suffix for.

Raises:

ValidationError – Raised when a parameter is invalid.

Returns:

A string that is either ‘st’, ‘nd’, ‘rd’, or ‘th’.

Return type:

str

Example:

>>> day_of_month_suffix(1)
'st'
>>> day_of_month_suffix(23)
'rd'
>>> day_of_month_suffix(11)
'th'
>>> day_of_month_suffix(22)
'nd'
>>> day_of_month_suffix(26)
'th'

timefmt._helpers.day_of_month_string(day: int) → str

Convert a numerical day of the month to a user-friendly string.

Parameters:

day (int) – The day of the month to convert.

Raises:

ValidationError – Raised when a parameter is invalid.

Returns:

A string with the day of the month and an appropriate suffix (‘st’, ‘nd’, ‘rd’, or ‘th’).

Return type:

str

Example:

>>> day_of_month_string(1)
'1st'
>>> day_of_month_string(23)
'23rd'
>>> day_of_month_string(11)
'11th'
>>> day_of_month_string(22)
'22nd'
>>> day_of_month_string(26)
'26th'

timefmt._helpers.timezone_name(datetime_in: datetime.datetime) → str

Get the full timezone name from a datetime.datetime object.

Parameters:

datetime_in (datetime.datetime) – The datetime.datetime object to get the timezone for.

Returns:

A human-readable string with the timezone name (defaults to OS-specific formatting).

Return type:

str

Example:

>>> from zoneinfo import ZoneInfo
>>> test_datetime = datetime.datetime(2023, 12, 31, 12, 23, 31, 379292, tzinfo=ZoneInfo("MST"))
>>> timezone_name(test_datetime)
'MST'
>>> test_datetime2 = datetime.datetime(2023, 12, 31, 12, 53, 10, 467258, tzinfo=ZoneInfo("EST"))
>>> timezone_name(test_datetime2)
'EST'