mycroft.util.format

The mycroft.util.format module provides various formatting functions for things like numbers, times, etc.

The focus of these formatting functions is to create human digestible content either as speech or in display form. It is also enables localization.

The module uses lingua-franca (https://github.com/mycroftai/lingua-franca) to do most of the actual parsing. However methods may be wrapped specifically for use in Mycroft Skills.

mycroft.util.format.nice_duration(duration, lang=None, speech=True, use_years=True, clock=False, resolution=TimeResolution.SECONDS)[source]

Convert duration in seconds to a nice spoken timespan

Accepts:

time, in seconds, or datetime.timedelta

Examples

duration = 60 -> “1:00” or “one minute” duration = 163 -> “2:43” or “two minutes forty three seconds” duration = timedelta(seconds=120) -> “2:00” or “two minutes”

Parameters
  • duration (int/float/datetime.timedelta) –

  • lang (str, optional) – a BCP-47 language code, None for default

  • speech (bool, opt) – format output for speech (True) or display (False)

  • use_years (bool, opt) – rtn years and days if True, total days if False

  • clock (bool, opt) – always format output like digital clock (see below)

  • resolution (mycroft.util.format.TimeResolution, optional) –

    lower bound

    mycroft.util.format.TimeResolution values:

    TimeResolution.YEARS TimeResolution.DAYS TimeResolution.HOURS TimeResolution.MINUTES TimeResolution.SECONDS TimeResolution.MILLISECONDS

    NOTE: nice_duration will not produce milliseconds unless that resolution is passed.

    NOTE: clock will produce digital clock-like output appropriate to resolution. Has no effect on resolutions DAYS or YEARS. Only applies to displayed output.

Returns

timespan as a string

Return type

str

mycroft.util.format.nice_duration_dt(date1, date2, lang=None, speech=True, use_years=True, clock=False, resolution=TimeResolution.SECONDS)[source]

Convert duration between datetimes to a nice spoken timespan

Accepts:

2 x datetime.datetime

Examples

date1 = datetime(2019, 3, 12), date2 = datetime(2019, 1, 1) -> “seventy days”

date1 = datetime(2019, 12, 25, 20, 30), date2 = datetime(2019, 10, 31, 8, 00), speech = False -> “55d 12:30”

Parameters
  • date1 (datetime.datetime) –

  • date2 (datetime.datetime) –

  • lang (str, optional) – a BCP-47 language code, None for default

  • speech (bool, opt) – format output for speech (True) or display (False)

  • use_years (bool, opt) – rtn years and days if True, total days if False

  • clock (bool, opt) – always format output like digital clock (see below)

  • resolution (mycroft.util.format.TimeResolution, optional) –

    lower bound

    mycroft.util.format.TimeResolution values:

    TimeResolution.YEARS TimeResolution.DAYS TimeResolution.HOURS TimeResolution.MINUTES TimeResolution.SECONDS

    NOTE: nice_duration_dt() cannot do TimeResolution.MILLISECONDS This will silently fall back on TimeResolution.SECONDS

    NOTE: clock will produce digital clock-like output appropriate to resolution. Has no effect on resolutions DAYS or YEARS. Only applies to displayed output.

Returns

timespan as a string

Return type

str