392 lines
15 KiB
Python
392 lines
15 KiB
Python
# Copyright 2017 Mycroft AI Inc.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
#
|
|
|
|
"""
|
|
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.
|
|
"""
|
|
import datetime
|
|
import warnings
|
|
|
|
from calendar import leapdays
|
|
from enum import Enum
|
|
|
|
# These are the main functions we are using lingua franca to provide
|
|
# TODO 21.08 - move nice_duration methods to Lingua Franca.
|
|
from lingua_franca.format import (
|
|
join_list,
|
|
nice_date,
|
|
nice_date_time,
|
|
nice_number,
|
|
nice_time,
|
|
nice_year,
|
|
pronounce_number
|
|
)
|
|
# TODO 21.08 - remove import of private method _translate_word
|
|
# Consider whether the remaining items here are necessary.
|
|
from lingua_franca.format import (NUMBER_TUPLE, DateTimeFormat,
|
|
date_time_format, expand_options,
|
|
_translate_word)
|
|
from padatious.util import expand_parentheses
|
|
|
|
|
|
class TimeResolution(Enum):
|
|
YEARS = 1
|
|
DAYS = 2
|
|
HOURS = 3
|
|
MINUTES = 4
|
|
SECONDS = 5
|
|
MILLISECONDS = 6
|
|
|
|
|
|
def _duration_handler(time1, lang=None, speech=True, *, time2=None,
|
|
use_years=True, clock=False,
|
|
resolution=TimeResolution.SECONDS):
|
|
"""Convert duration in seconds to a nice spoken timespan.
|
|
|
|
Used as a handler by nice_duration and nice_duration_dt.
|
|
|
|
Accepts:
|
|
datetime.timedelta, or
|
|
seconds (int/float), or
|
|
2 x datetime.datetime
|
|
|
|
Examples:
|
|
time1 = 60 -> "1:00" or "one minute"
|
|
time1 = 163 -> "2:43" or "two minutes forty three seconds"
|
|
time1 = timedelta(seconds=120) -> "2:00" or "two minutes"
|
|
|
|
time1 = datetime(2019, 3, 12),
|
|
time2 = datetime(2019, 1, 1) -> "seventy days"
|
|
|
|
Args:
|
|
time1: int/float seconds, OR datetime.timedelta, OR datetime.datetime
|
|
time2 (datetime, optional): subtracted from time1 if time1 is 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
|
|
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:
|
|
str: timespan as a string
|
|
"""
|
|
_leapdays = 0
|
|
_input_resolution = resolution
|
|
milliseconds = 0
|
|
|
|
type1 = type(time1)
|
|
|
|
if time2:
|
|
type2 = type(time2)
|
|
if type1 is not type2:
|
|
raise Exception("nice_duration() can't combine data types: "
|
|
"{} and {}".format(type1, type2))
|
|
elif type1 is datetime.datetime:
|
|
duration = time1 - time2
|
|
_leapdays = (abs(leapdays(time1.year, time2.year)))
|
|
|
|
# when operating on datetimes, refuse resolutions that
|
|
# would result in bunches of trailing zeroes
|
|
if all([time1.second == 0, time2.second == 0,
|
|
resolution.value >= TimeResolution.SECONDS.value]):
|
|
resolution = TimeResolution.MINUTES
|
|
if all([time1.minute == 0, time2.minute == 0,
|
|
resolution.value == TimeResolution.MINUTES.value]):
|
|
resolution = TimeResolution.HOURS
|
|
if all([time1.hour == 0, time2.hour == 0,
|
|
resolution.value == TimeResolution.HOURS.value]):
|
|
resolution = TimeResolution.DAYS
|
|
|
|
else:
|
|
_tmp = warnings.formatwarning
|
|
warnings.formatwarning = lambda msg, * \
|
|
args, **kwargs: "{}\n".format(msg)
|
|
warning = ("WARN: mycroft.util.format.nice_duration_dt() can't "
|
|
"subtract " + str(type1) + ". Ignoring 2nd "
|
|
"argument '" + str(time2) + "'.")
|
|
warnings.warn(warning)
|
|
warnings.formatwarning = _tmp
|
|
duration = time1
|
|
else:
|
|
duration = time1
|
|
|
|
# Pull decimal portion of seconds, if present, to use for milliseconds
|
|
if isinstance(duration, float):
|
|
milliseconds = str(duration).split('.')[1]
|
|
if speech:
|
|
milliseconds = milliseconds[:2]
|
|
else:
|
|
milliseconds = milliseconds[:3]
|
|
milliseconds = float("0." + milliseconds)
|
|
|
|
# Cast duration to datetime.timedelta for human-friendliness
|
|
if not isinstance(duration, datetime.timedelta):
|
|
duration = datetime.timedelta(seconds=duration)
|
|
|
|
days = duration.days
|
|
if use_years:
|
|
days -= _leapdays if days > 365 else 0
|
|
years = days // 365
|
|
else:
|
|
years = 0
|
|
days = days % 365 if years > 0 else days
|
|
|
|
# We already stored milliseconds. Now we want the integer part.
|
|
seconds = duration.seconds
|
|
minutes = seconds // 60
|
|
seconds %= 60
|
|
hours = minutes // 60
|
|
minutes %= 60
|
|
|
|
if speech:
|
|
out = ""
|
|
if years > 0:
|
|
out += pronounce_number(years, lang) + " "
|
|
out += _translate_word("year" if years == 1 else "years", lang)
|
|
|
|
if days > 0 and resolution.value > TimeResolution.YEARS.value:
|
|
if out:
|
|
out += " "
|
|
out += pronounce_number(days, lang) + " "
|
|
out += _translate_word("day" if days == 1 else "days", lang)
|
|
|
|
if hours > 0 and resolution.value > TimeResolution.DAYS.value:
|
|
if out:
|
|
out += " "
|
|
out += pronounce_number(hours, lang) + " "
|
|
out += _translate_word("hour" if hours == 1 else "hours", lang)
|
|
|
|
if minutes > 0 and resolution.value > TimeResolution.HOURS.value:
|
|
if out:
|
|
out += " "
|
|
out += pronounce_number(minutes, lang) + " "
|
|
out += _translate_word("minute" if minutes ==
|
|
1 else "minutes", lang)
|
|
|
|
if ((seconds > 0 and resolution.value >=
|
|
TimeResolution.SECONDS.value) or
|
|
(milliseconds > 0 and resolution.value ==
|
|
TimeResolution.MILLISECONDS.value)):
|
|
|
|
if resolution.value == TimeResolution.MILLISECONDS.value:
|
|
seconds += milliseconds
|
|
if out:
|
|
out += " "
|
|
# Throw "and" between minutes and seconds if duration < 1 hour
|
|
if len(out.split()) > 3 or seconds < 1:
|
|
out += _translate_word("and", lang) + " "
|
|
# speaking "zero point five seconds" is better than "point five"
|
|
out += pronounce_number(seconds, lang) + " "
|
|
out += _translate_word("second" if seconds ==
|
|
1 else "seconds", lang)
|
|
|
|
else:
|
|
# M:SS, MM:SS, H:MM:SS, Dd H:MM:SS format
|
|
|
|
_seconds_str = ("0" + str(seconds)) if seconds < 10 else str(seconds)
|
|
|
|
out = ""
|
|
if years > 0:
|
|
out = str(years) + "y "
|
|
if days > 0 and resolution.value > TimeResolution.YEARS.value:
|
|
out += str(days) + "d "
|
|
if (hours > 0 and resolution.value > TimeResolution.DAYS.value) or \
|
|
(clock and resolution is TimeResolution.HOURS):
|
|
out += str(hours)
|
|
|
|
if resolution.value == TimeResolution.MINUTES.value and not clock:
|
|
out += (("h " + str(minutes) + "m") if hours > 0
|
|
else str(minutes) + "m")
|
|
elif (minutes > 0 and resolution.value > TimeResolution.HOURS.value) \
|
|
or (clock and resolution.value >= TimeResolution.HOURS.value):
|
|
if hours != 0 or (clock and resolution is TimeResolution.HOURS):
|
|
out += ":"
|
|
if minutes < 10:
|
|
out += "0"
|
|
out += str(minutes) + ":"
|
|
if (seconds > 0 and resolution.value >
|
|
TimeResolution.MINUTES.value) or clock:
|
|
out += _seconds_str
|
|
else:
|
|
out += "00"
|
|
# if we have seconds but no minutes...
|
|
elif (seconds > 0 or clock) and resolution.value > \
|
|
TimeResolution.MINUTES.value:
|
|
# check if output ends in hours
|
|
try:
|
|
if str(hours) == out.split()[-1]:
|
|
out += ":"
|
|
except IndexError:
|
|
pass
|
|
out += ("00:" if hours > 0 else "0:") + _seconds_str
|
|
|
|
if (milliseconds > 0 or clock) and resolution.value \
|
|
== TimeResolution.MILLISECONDS.value:
|
|
_mill = str(milliseconds).split(".")[1]
|
|
# right-pad milliseconds to three decimal places
|
|
while len(_mill) < 3:
|
|
_mill += "0"
|
|
# make sure output < 1s still formats correctly
|
|
if out == "":
|
|
out = "0:00"
|
|
else:
|
|
if (str(hours) == out.split()[-1]) and ":" not in out:
|
|
out += ":00:00"
|
|
# only append milliseconds to output that contains
|
|
# minutes and/or seconds
|
|
if ":" in out:
|
|
out += "." + _mill
|
|
|
|
# If this evaluates True, out currently ends in hours: "1d 12"
|
|
if out and all([resolution.value >= TimeResolution.HOURS.value,
|
|
":" not in out, out[-1] != "m", hours > 0]):
|
|
# to "1d 12h"
|
|
out += "h"
|
|
out = out.strip()
|
|
|
|
if not out:
|
|
out = "zero " if speech else "0"
|
|
if _input_resolution == TimeResolution.YEARS:
|
|
out += "years" if speech else "y"
|
|
elif _input_resolution == TimeResolution.DAYS:
|
|
out += "days" if speech else "d"
|
|
elif _input_resolution == TimeResolution.HOURS:
|
|
out += "hours" if speech else "h"
|
|
elif _input_resolution == TimeResolution.MINUTES:
|
|
if speech:
|
|
out = "under a minute" if seconds > 0 else "zero minutes"
|
|
else:
|
|
out = "0m"
|
|
else:
|
|
out = "zero seconds" if speech else "0:00"
|
|
|
|
return out
|
|
|
|
|
|
def nice_duration(duration, lang=None, speech=True, use_years=True,
|
|
clock=False, resolution=TimeResolution.SECONDS):
|
|
""" 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"
|
|
|
|
Args:
|
|
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:
|
|
str: timespan as a string
|
|
"""
|
|
return _duration_handler(duration, lang=lang, speech=speech,
|
|
use_years=use_years, resolution=resolution,
|
|
clock=clock)
|
|
|
|
|
|
def nice_duration_dt(date1, date2, lang=None, speech=True, use_years=True,
|
|
clock=False, resolution=TimeResolution.SECONDS):
|
|
""" 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"
|
|
|
|
Args:
|
|
date1, 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:
|
|
str: timespan as a string
|
|
"""
|
|
try:
|
|
big = max(date1, date2)
|
|
small = min(date1, date2)
|
|
except(TypeError):
|
|
big = date1
|
|
small = date2
|
|
return _duration_handler(big, lang=lang, speech=speech, time2=small,
|
|
use_years=use_years, resolution=resolution,
|
|
clock=clock)
|