vals.fmt_duration()

Format values as time duration strings.

Usage

Source

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
)

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']