vals.fmt_duration

vals.fmt_duration(
    x,
    input_units=None,
    output_units=None,
    duration_style='narrow',
    trim_zero_units=True,
    max_output_units=None,
    pattern='{x}',
    use_seps=True,
    sep_mark=',',
    force_sign=False,
    locale=None,
)

Format values as time duration strings.

With numeric values in a list, we can transform those to values of time duration with various human readable styles. The val_fmt_duration() function allows for formatting of duration values to narrow, wide, colon-separated, and ISO 8601 forms.

Parameters

x : X

A list of numeric values to be formatted as durations.

input_units : str | None = None

The time units of the input numeric values. Required for numeric input. The accepted units are: "seconds", "minutes", "hours", "days", and "weeks".

output_units : 'str | list[str] | None' = None

Controls the output time units. The default (None) means that output units will be automatically chosen. Can be a list of keywords from: "weeks", "days", "hours", "minutes", or "seconds".

duration_style : str = 'narrow'

Style for representing duration values. One of "narrow" (default, e.g., "1d 8h 24m"), "wide" (e.g., "1 day 8 hours 24 minutes"), "colon-sep" (e.g., "1/08:24:00"), or "iso" (e.g., "P1DT8H24M").

trim_zero_units : 'bool | list[str]' = True

Provides methods to remove output time units that have zero values. By default this is True. Can also be a list of "leading", "trailing", and/or "internal".

max_output_units : int | None = None

Maximum number of time units to display. By default (None), all possible time units will be displayed.

pattern : str = '{x}'

A formatting pattern that allows for decoration of the formatted value.

use_seps : bool = True

Whether to use digit group separators.

sep_mark : str = ','

The string to use as a separator between groups of digits.

force_sign : bool = False

Should the positive sign be shown for positive values?

locale : str | None = None

An optional locale identifier for formatting values.

Returns

: list[str]

A list of formatted values is returned.

Examples

from great_tables import vals

vals.fmt_duration([3661, 86400, 172800], input_units="seconds")

['1h 1m 1s', '1d', '2d']