From c6bc8dbadfffbb7164b2075556c42de6e5c396e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=85ke=20Forslund?= Date: Wed, 5 May 2021 10:56:22 +0200 Subject: [PATCH] Add approprate blank lines to fix phinxdoc warnings --- mycroft/util/format.py | 39 +++++++++++++++++++++++++++------------ mycroft/util/parse.py | 21 +++++++++++++++------ 2 files changed, 42 insertions(+), 18 deletions(-) diff --git a/mycroft/util/format.py b/mycroft/util/format.py index d8b1faa907a0..803046168605 100644 --- a/mycroft/util/format.py +++ b/mycroft/util/format.py @@ -39,14 +39,17 @@ def nice_number(number, lang=None, speech=True, denominators=None): - """Format a float to human readable functions + """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 + Args: number (int or float): the float to format lang (str): code for the language to use speech (bool): format for speech (True) or display (False) denominators (iter of ints): denominators to use, default [1 .. 20] + Returns: (str): The formatted string. """ @@ -56,16 +59,18 @@ def nice_number(number, lang=None, speech=True, denominators=None): def nice_time(dt, lang=None, speech=True, use_24hour=False, use_ampm=False): - """ - Format a time to a comfortable human format + """Format a time to a comfortable human format. + For example, generate 'five thirty' for speech or '5:30' for text display. + Args: 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: (str): The formatted time string """ @@ -75,14 +80,16 @@ def nice_time(dt, lang=None, speech=True, use_24hour=False, def pronounce_number(number, lang=None, places=2, short_scale=True, scientific=False): - """ - Convert a number to it's spoken equivalent + """Convert a number to it's spoken equivalent + For example, '5' would be 'five' + Args: number: the number to pronounce short_scale (bool) : use short (True) or long scale (False) https://en.wikipedia.org/wiki/Names_of_large_numbers scientific (bool) : convert and pronounce in scientific notation + Returns: (str): The pronounced number """ @@ -91,9 +98,10 @@ def pronounce_number(number, lang=None, places=2, short_scale=True, def nice_date(dt, lang=None, now=None): - """ - Format a datetime to a pronounceable date - For example, generates 'tuesday, june the fifth, 2018' + """Format a datetime to a pronounceable date. + + For example, generates 'tuesday, june the fifth, 2018'. + Args: dt (datetime): date to format (assumes already in local timezone) lang (string): the language to use, use Mycroft default language if not @@ -102,6 +110,7 @@ def nice_date(dt, lang=None, now=None): 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: (str): The formatted date string """ @@ -112,7 +121,8 @@ def nice_date_time(dt, lang=None, now=None, use_24hour=False, use_ampm=False): """Format a datetime to a pronounceable date and time. - For example, generate 'tuesday, june the fifth, 2018 at five thirty' + For example, generate 'tuesday, june the fifth, 2018 at five thirty'. + Args: dt (datetime): date to format (assumes already in local timezone) lang (string): the language to use, use Mycroft default language if @@ -124,6 +134,7 @@ def nice_date_time(dt, lang=None, now=None, use_24hour=False, 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: (str): The formatted date time string """ @@ -134,13 +145,15 @@ def nice_date_time(dt, lang=None, now=None, use_24hour=False, def nice_year(dt, lang=None, bc=False): """Format a datetime to a pronounceable year. - For example, generate 'nineteen-hundred and eighty-four' for year 1984 + For example, generate 'nineteen-hundred and eighty-four' for year 1984. + Args: dt (datetime): date to format (assumes already in local timezone) lang (string): the language to use, use Mycroft default language if not provided bc (bool) pust B.C. after the year (python does not support dates B.C. in datetime) + Returns: (str): The formatted year string """ @@ -159,8 +172,9 @@ class TimeResolution(Enum): 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 + """Convert duration in seconds to a nice spoken timespan. + + Used as a handler by nice_duration and nice_duration_dt. Accepts: datetime.timedelta, or @@ -421,6 +435,7 @@ def nice_duration(duration, lang=None, speech=True, use_years=True, TimeResolution.MINUTES TimeResolution.SECONDS TimeResolution.MILLISECONDS + NOTE: nice_duration will not produce milliseconds unless that resolution is passed. diff --git a/mycroft/util/parse.py b/mycroft/util/parse.py index 1d1a8200c0c3..f59c273356a9 100644 --- a/mycroft/util/parse.py +++ b/mycroft/util/parse.py @@ -24,7 +24,7 @@ This module provides the Mycroft localization for time and so forth as well as provide a convenience. -The module does implement some useful functions like basic fuzzy matchin. +The module does implement some useful functions like basic fuzzy matching. """ from difflib import SequenceMatcher @@ -54,6 +54,7 @@ def _log_unsupported_language(language, supported_languages): def fuzzy_match(x, against): """Perform a 'fuzzy' comparison between two strings. + Returns: float: match percentage -- 1.0 for perfect match, down to 0.0 for no match at all. @@ -93,6 +94,7 @@ def match_one(query, choices): def extract_numbers(text, short_scale=True, ordinals=False, lang=None): """ Takes in a string and extracts a list of numbers. + Args: text (str): the string to extract a number from short_scale (bool): Use "short scale" or "long scale" for large @@ -101,6 +103,7 @@ def extract_numbers(text, short_scale=True, ordinals=False, lang=None): See https://en.wikipedia.org/wiki/Names_of_large_numbers ordinals (bool): consider ordinal numbers, e.g. third=3 instead of 1/3 lang (str): the BCP-47 code for the language to use, None uses default + Returns: list: list of extracted numbers as floats, or empty list if none found """ @@ -110,6 +113,7 @@ def extract_numbers(text, short_scale=True, ordinals=False, lang=None): def extract_number(text, short_scale=True, ordinals=False, lang=None): """Takes in a string and extracts a number. + Args: text (str): the string to extract a number from short_scale (bool): Use "short scale" or "long scale" for large @@ -118,6 +122,7 @@ def extract_number(text, short_scale=True, ordinals=False, lang=None): See https://en.wikipedia.org/wiki/Names_of_large_numbers ordinals (bool): consider ordinal numbers, e.g. third=3 instead of 1/3 lang (str): the BCP-47 code for the language to use, None uses default + Returns: (int, float or False): The number extracted or False if the input text contains no numbers @@ -128,13 +133,16 @@ def extract_number(text, short_scale=True, ordinals=False, lang=None): def normalize(text, lang=None, remove_articles=True): """Prepare a string for parsing + This function prepares the given text for parsing by making numbers consistent, getting rid of contractions, etc. + Args: text (str): the string to normalize lang (str): the BCP-47 code for the language to use, None uses default remove_articles (bool): whether to remove articles (like 'a', or 'the'). True by default. + Returns: (str): The normalized string. """ @@ -201,6 +209,7 @@ def extract_duration(text, lang=None): "10 minute" "2 and a half hours" "3 days 8 hours 10 minutes and 49 seconds" + into an int, representing the total number of seconds. The words used in the duration will be consumed, and @@ -214,11 +223,11 @@ def extract_duration(text, lang=None): lang (str): the BCP-47 code for the language to use, None uses default Returns: - (timedelta, str): - A tuple containing the duration and the remaining text - not consumed in the parsing. The first value will - be None if no duration is found. The text returned - will have whitespace stripped from the ends. + (timedelta, str): A tuple containing the duration and the remaining + text not consumed in the parsing. The first value + will be None if no duration is found. The text + returned will have whitespace stripped from the + ends. """ lang_code = get_primary_lang_code(lang) return lingua_franca.parse.extract_duration(text, lang_code)