"""
Time duration conversion utilities.
This module provides helper functions for converting time durations into
standardized numeric or string formats. It supports raw numeric values
interpreted as seconds, as well as string duration formats such as
``"1h30m"`` or ``"0:03:53.540000"`` parsed by :mod:`pytimeparse`.
The main public utilities are:
* :func:`time_to_duration` - Convert any supported time format into seconds.
* :func:`time_to_delta_str` - Convert time durations into a ``datetime.timedelta`` string.
Example::
>>> from hbutils.scale.time import time_to_duration, time_to_delta_str
>>> time_to_duration("1h343m67.4s")
24247.4
>>> time_to_delta_str(233.54)
'0:03:53.540000'
.. note::
The parsing of string durations is delegated to :func:`pytimeparse.parse`.
Unsupported strings may result in a ``None`` return value from the parser.
"""
import datetime
from typing import Union
from pytimeparse import parse as parse_duration
__all__ = ['time_to_duration', 'time_to_delta_str']
_TIME_TYPING = Union[float, int, str]
[docs]
def time_to_duration(time_: _TIME_TYPING) -> Union[float, int]:
"""
Turn any types of time duration into time value in seconds.
:param time_: Any types of time duration, can be numeric (seconds) or string format.
:type time_: Union[int, float, str]
:return: Time duration value in seconds.
:rtype: Union[float, int]
:raises TypeError: If the input type is not int, float, or str.
:raises TypeError: If the string input is not parsable by :mod:`pytimeparse`.
:raises ValueError: If the string input is not parsable by :mod:`pytimeparse`.
Examples::
>>> from hbutils.scale import time_to_duration
>>> time_to_duration(23344)
23344
>>> time_to_duration(233.54)
233.54
>>> time_to_duration('1h343m67.4s')
24247.4
>>> time_to_duration('0:03:53.540000')
233.54
"""
if isinstance(time_, (float, int)):
return time_
elif isinstance(time_, str):
return parse_duration(time_)
else:
raise TypeError('{float}, {int} or {str} expected but {actual} found.'.format(
float=float.__name__,
int=int.__name__,
str=str.__name__,
actual=type(time_).__name__,
))
[docs]
def time_to_delta_str(time_: _TIME_TYPING) -> str:
"""
Turn any types of time duration into time value in formatted string.
This function converts various time duration formats into a standardized
string representation using the format ``H:MM:SS`` or ``H:MM:SS.ffffff`` for
durations with fractional seconds.
:param time_: Any types of time duration, can be numeric (seconds) or string format.
:type time_: Union[int, float, str]
:return: Time duration value in formatted string (e.g., ``"6:29:04"`` or
``"0:03:53.540000"``).
:rtype: str
:raises TypeError: If the input type is not int, float, or str (raised by
:func:`time_to_duration`).
Examples::
>>> from hbutils.scale import time_to_delta_str
>>> time_to_delta_str(23344)
'6:29:04'
>>> time_to_delta_str(233.54)
'0:03:53.540000'
>>> time_to_delta_str('1h343m67.4s')
'6:44:07.400000'
"""
return str(datetime.timedelta(seconds=time_to_duration(time_)))