timefmt

Provides methods to manipulate and format various time-based objects into human-readable strings.

Submodules

Package 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.

auto(time_in[, long])

Automatically convert a datetime.datetime or datetime.timedelta object to a string and return it.
class timefmt.SplitTime

Data class for holding split time values.

weeks: int
days: int
hours: int
minutes: int
seconds: int
milliseconds: int | float
timefmt.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.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.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.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'
timefmt.auto(time_in: datetime.datetime | datetime.timedelta, long: bool = False)

Automatically convert a datetime.datetime or datetime.timedelta object to a string and return it.

Parameters:

  • time_in (datetime.datetime | datetime.timedelta) – The object to convert.

  • long – If we should return the long or short version.

Raises:

onecondition.ValidationError – If the time_in is not a datetime.datetime or datetime.timedelta object

Returns:

The input time in a human-readable format.

Return type:

str

Example:
>>> from freezegun import freeze_time
>>> freezer = freeze_time("2023-12-31")
>>> r = freezer.start()

>>> from zoneinfo import ZoneInfo
>>> test_datetime = datetime.datetime(2023, 12, 31, 12, 23, 31, 379292, tzinfo=ZoneInfo("MST"))
>>> auto(test_datetime)
'12:23:31 PM'
>>> auto(test_datetime, long=True)
'12:23:31 PM MST'
>>> test_timedelta = datetime.timedelta(hours=1000, seconds=9999)
>>> auto(test_timedelta)
'5W 6D 18:46:39'
>>> auto(test_timedelta, long=True)
'5 weeks, 6 days, 18 hours, 46 minutes, and 39 seconds'
>>> auto(42)
Traceback (most recent call last):
    ...
onecondition.ValidationError: Value `42` must must be either a datetime or timedelta object, not a <class 'int'>