mycroft.util.format

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

The module uses lingua-franca (https://github.com/mycroftai/lingua-franca) to do most of the actual parsing.

The focus of these formatting functions is to create natural sounding speech and allow localization.

class mycroft.util.format.TimeResolution[source]

An enumeration.

mycroft.util.format.nice_date(dt, lang=None, now=None)[source]

Format a datetime to a pronounceable date For example, generates ‘tuesday, june the fifth, 2018’ :param dt: date to format (assumes already in local timezone) :type dt: datetime :param lang: the language to use, use Mycroft default language if not

provided

Parameters

now (datetime) – Current date. If provided, the returned date for speech will be shortened accordingly: No year is returned if now is in the same year as td, no month is returned if now is in the same month as td. If now and td is the same day, ‘today’ is returned.

Returns

The formatted date string

Return type

(str)

mycroft.util.format.nice_date_time(dt, lang=None, now=None, use_24hour=False, use_ampm=False)[source]

Format a datetime to a pronounceable date and time.

For example, generate ‘tuesday, june the fifth, 2018 at five thirty’ :param dt: date to format (assumes already in local timezone) :type dt: datetime :param lang: the language to use, use Mycroft default language if

not provided

Parameters
  • now (datetime) – Current date. If provided, the returned date for speech will be shortened accordingly: No year is returned if now is in the same year as td, no month is returned if now is in the same month as td. If now and td is the same day, ‘today’ is returned.

  • use_24hour (bool) – output in 24-hour/military or 12-hour format

  • use_ampm (bool) – include the am/pm for 12-hour format

Returns

The formatted date time string

Return type

(str)

mycroft.util.format.nice_duration(duration, lang=None, speech=True, use_years=True, clock=False, resolution=<TimeResolution.SECONDS: 5>)[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: 5>)[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
  • date2 (date1,) –

  • 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

mycroft.util.format.nice_number(number, lang=None, speech=True, denominators=None)[source]

Format a float to human readable functions This function formats a float to human understandable functions. Like 4.5 becomes 4 and a half for speech and 4 1/2 for text :param number: the float to format :type number: int or float :param lang: code for the language to use :type lang: str :param speech: format for speech (True) or display (False) :type speech: bool :param denominators: denominators to use, default [1 .. 20] :type denominators: iter of ints

Returns

The formatted string.

Return type

(str)

mycroft.util.format.nice_time(dt, lang=None, speech=True, use_24hour=False, use_ampm=False)[source]

Format a time to a comfortable human format For example, generate ‘five thirty’ for speech or ‘5:30’ for text display. :param dt: date to format (assumes already in local timezone) :type dt: datetime :param lang: code for the language to use :type lang: str :param speech: format for speech (default/True) or display (False) :type speech: bool :param use_24hour: output in 24-hour/military or 12-hour format :type use_24hour: bool :param use_ampm: include the am/pm for 12-hour format :type use_ampm: bool

Returns

The formatted time string

Return type

(str)

mycroft.util.format.nice_year(dt, lang=None, bc=False)[source]

Format a datetime to a pronounceable year.

For example, generate ‘nineteen-hundred and eighty-four’ for year 1984 :param dt: date to format (assumes already in local timezone) :type dt: datetime :param lang: the language to use, use Mycroft default language if :type lang: string :param not provided: :param bc: B.C. in datetime) :type bc: bool

Returns

The formatted year string

Return type

(str)

mycroft.util.format.pronounce_number(number, lang=None, places=2, short_scale=True, scientific=False)[source]

Convert a number to it’s spoken equivalent For example, ‘5’ would be ‘five’ :param number: the number to pronounce :param short_scale: use short (True) or long scale (False)

Parameters

scientific (bool) – convert and pronounce in scientific notation

Returns

The pronounced number

Return type

(str)