time_delta

Module for time difference formatting (e.g. “4 days 15 hours”, “8h 59m”).

Supports several output lengths and can be customized even more.

class pytermor.formatters.time_delta.TimeDeltaFormatter(max_len: int, units: List[TimeUnit], allow_negative: bool, unit_separator: str | None = None, plural_suffix: str | None = None, overflow_msg: str | None = 'OVERFLOW')

Formatter for time intervals. Key feature of this formatter is ability to combine two units and display them simultaneously, e.g. print “3h 48min” instead of “228 mins” or “3 hours”,

Example output:

“10 secs”, “5 mins”, “4h 15min”, “5d 22h”

allow_negative: bool

format(seconds: float) → str

max_len: int

overflow_msg: str | None = 'OVERFLOW'

plural_suffix: str | None = None

unit_separator: str | None = None

units: List[TimeUnit]

class pytermor.formatters.time_delta.TimeDeltaFormatterRegistry

Simple registry for storing formatters and selecting the suitable one by max output length.

find_matching(max_len: int) → TimeDeltaFormatter | None

get_by_max_len(max_len: int) → TimeDeltaFormatter | None

get_longest() → TimeDeltaFormatterRegistry | None

get_shortest() → TimeDeltaFormatterRegistry | None

register(*formatters: TimeDeltaFormatter)

class pytermor.formatters.time_delta.TimeUnit(name: 'str', in_next: 'int' = None, custom_short: 'str' = None, collapsible_after: 'int' = None, overflow_afer: 'int' = None)

collapsible_after: int = None

custom_short: str = None

in_next: int = None

name: str

overflow_afer: int = None

pytermor.formatters.time_delta.format_time_delta(seconds: float, max_len: Optional[int] = None) → str

Format time delta using suitable format (which depends on max_len argument). Key feature of this formatter is ability to combine two units and display them simultaneously, e.g. print “3h 48min” instead of “228 mins” or “3 hours”,

Formatters are defined for max_len= 3, 4, 6 and 10. Therefore, you can pass in any value from 3 incl. and it’s guarenteed that result’s length will be less or equal to required length. If omitted longest registred will be used.

Example output:

• max_len=3: “10s”, “5m”, “4h”, “5d”

• max_len=4: “10 s”, “5 m”, “4 h”, “5 d”

• max_len=6: “10 sec”, “5 min”, “4h 15m”, “5d 22h”

• max_len=10: “10 secs”, “5 mins”, “4h 15min”, “5d 22h”

Parameters

• seconds – Value to format

• max_len – Maximum output string length (total)

Returns

Formatted string