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 natural sounding speech and allow localization.

mycroft.util.format.NUMBER_TUPLE

alias of mycroft.util.format.number

mycroft.util.format.expand_options(parentheses_line: str) → list[source]

Convert ‘test (a|b)’ -> [‘test a’, ‘test b’] :param parentheses_line: Input line to expand

Returns:List of expanded possibilities
mycroft.util.format.join_list(items, connector, sep=None, lang=None)[source]

Join a list into a phrase using the given connector word

Examples

join_list([1,2,3], “and”) -> “1, 2 and 3” join_list([1,2,3], “and”, “;”) -> “1; 2 and 3”

Parameters:
  • items (array) – items to be joined
  • connector (str) – connecting word (resource name), like “and” or “or”
  • sep (str, optional) – separator character, default = “,”
Returns:

the connected list phrase

Return type:

str

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’

Parameters:
  • dt (datetime) – date to format (assumes already in local timezone)
  • lang (string) – the language to use, use Mycroft default language if not provided
  • 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)[source]

Convert duration in seconds to a nice spoken timespan

Examples

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

Parameters:
  • duration – time, in seconds
  • lang (str, optional) – a BCP-47 language code, None for default
  • speech (bool) – format for speech (True) or display (False)
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.

Parameters:
  • dt (datetime) – date to format (assumes already in local timezone)
  • lang (str) – code for the language to use
  • speech (bool) – format for speech (default/True) or display (False)
  • 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 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

Parameters:
  • dt (datetime) – date to format (assumes already in local timezone)
  • lang (string) – the language to use, use Mycroft default language if
  • provided (not) –
  • bc (bool) – B.C. in datetime)
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’

Parameters:
Returns:

The pronounced number

Return type:

(str)