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.
-
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
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
-
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)