Skip to content

Commit

Permalink
Merge pull request #191 from MycroftAI/bugfix/docstring-cleanup
Browse files Browse the repository at this point in the history 
Clean up of public docstrings
  • Loading branch information
@krisgesling
krisgesling authored May 7, 2021
2 parents d876153 + abf7575 commit 49912ba
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 35 deletions.
56 changes: 39 additions & 17 deletions lingua_franca/format.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,8 @@ def _translate_word(name, lang=''):
Args:
name (str): Word name. Returned as the default value if not translated
lang (str): Language code, e.g. "en-us"
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
Returns:
str: translated version of resource name
Expand All @@ -59,7 +60,7 @@ def _translate_word(name, lang=''):
lang_code = lang if is_supported_full_lang(lang) else \
get_full_lang_code(lang)

filename = resolve_resource_file(join("text", lang_code, name+".word"))
filename = resolve_resource_file(join("text", lang_code, name + ".word"))
if filename:
# open the file
try:
Expand Down Expand Up @@ -137,7 +138,7 @@ def _number_strings(self, number, lang):
x_in_x000 = self.lang_config[lang]['number'].get(str(int(
number % 10000 / 1000))) or str(int(number % 10000 / 1000))
x0_in_x000 = self.lang_config[lang]['number'].get(str(int(
number % 10000 / 1000)*10)) or str(int(number % 10000 / 1000)*10)
number % 10000 / 1000) * 10)) or str(int(number % 10000 / 1000) * 10)
x_in_0x00 = self.lang_config[lang]['number'].get(str(int(
number % 1000 / 100)) or str(int(number % 1000 / 100)))

Expand Down Expand Up @@ -249,7 +250,8 @@ def nice_number(number, lang='', speech=True, denominators=None):
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
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
speech (bool): format for speech (True) or display (False)
denominators (iter of ints): denominators to use, default [1 .. 20]
Returns:
Expand All @@ -269,7 +271,8 @@ def nice_time(dt, lang='', speech=True, use_24hour=False,
Args:
dt (datetime): date to format (assumes already in local timezone)
lang (str): code for the language to use
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
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
Expand All @@ -290,6 +293,9 @@ def pronounce_number(number, lang='', places=2, short_scale=True,
Args:
number: the number to pronounce
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
places (int): number of decimal places to express, default 2
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
Expand All @@ -304,14 +310,16 @@ def nice_date(dt, lang='', now=None):
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
provided
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
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:
(str): The formatted date string
"""
Expand All @@ -330,8 +338,8 @@ def nice_date_time(dt, lang='', now=None, use_24hour=False,
Args:
dt (datetime): date to format (assumes already in local timezone)
lang (string): the language to use, use Mycroft default language if
not provided
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
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
Expand All @@ -358,8 +366,8 @@ def nice_year(dt, lang='', bc=False):
Args:
dt (datetime): date to format (assumes already in local timezone)
lang (string): the language to use, use Mycroft default language if
not provided
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
bc (bool) pust B.C. after the year (python does not support dates
B.C. in datetime)
Returns:
Expand All @@ -382,8 +390,10 @@ def nice_duration(duration, lang='', speech=True):
Args:
duration: time, in seconds
lang (str, optional): a BCP-47 language code, None for default
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
speech (bool): format for speech (True) or display (False)
Returns:
str: timespan as a string
"""
Expand All @@ -392,7 +402,8 @@ def nice_duration(duration, lang='', speech=True):
warn(NoneLangWarning)
lang = get_default_loc()
if not is_supported_full_lang(lang):
# TODO deprecated; delete when 'lang=None' and 'lang=invalid' are removed
# TODO deprecated; delete when 'lang=None' and 'lang=invalid' are
# removed
try:
lang = get_full_lang_code(lang)
except UnsupportedLanguageError:
Expand Down Expand Up @@ -454,7 +465,7 @@ def nice_duration(duration, lang='', speech=True):
out += str(hours) + ":"
if minutes < 10 and (hours > 0 or days > 0):
out += "0"
out += str(minutes)+":"
out += str(minutes) + ":"
if seconds < 10:
out += "0"
out += str(seconds)
Expand All @@ -470,9 +481,11 @@ def join_list(items, connector, sep=None, lang=''):
join_list([1,2,3], "and", ";") -> "1; 2 and 3"
Args:
items(array): items to be joined
connector(str): connecting word (resource name), like "and" or "or"
sep(str, optional): separator character, default = ","
items (array): items to be joined
connector (str): connecting word (resource name), like "and" or "or"
sep (str, optional): separator character, default = ","
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
Returns:
str: the connected list phrase
"""
Expand Down Expand Up @@ -503,8 +516,10 @@ def expand_parentheses(sent):
Will it pour today?
Will it pour tomorrow?
Will it pour?
Args:
sent (list<str>): List of tokens in sentence
Returns:
list<list<str>>: Multiple possible sentences from original
"""
Expand All @@ -514,8 +529,10 @@ def expand_parentheses(sent):
def expand_options(parentheses_line: str) -> list:
"""
Convert 'test (a|b)' -> ['test a', 'test b']
Args:
parentheses_line: Input line to expand
Returns:
List of expanded possibilities
"""
Expand All @@ -537,6 +554,11 @@ def nice_response(text, lang=''):
exponents in the following primary language codes:
da de nl sv
Args:
text (str): input text to sanitize
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
Example:
assertEqual(nice_response_de("dies ist der 31. mai"),
"dies ist der einunddreißigste mai")
Expand Down
47 changes: 29 additions & 18 deletions lingua_franca/parse.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,12 @@
populate_localized_function_dict("parse", langs=get_active_langs())


def fuzzy_match(x, against):
def fuzzy_match(x: str, against: str) -> float:
"""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.
match percentage -- 1.0 for perfect match,
down to 0.0 for no match at all.
"""
return SequenceMatcher(None, x, against).ratio()

Expand All @@ -46,11 +47,12 @@ def match_one(query, choices):
"""
Find best match from a list or dictionary given an input
Arguments:
query: string to test
choices: list or dictionary of choices
Args:
query (str): string to test
choices (list): list or dictionary of choices
Returns: tuple with best match, score
Returns:
tuple: (best match, score)
"""
if isinstance(choices, dict):
_choices = list(choices.keys())
Expand Down Expand Up @@ -83,7 +85,8 @@ def extract_numbers(text, short_scale=True, ordinals=False, lang=''):
is now common in most English speaking countries.
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
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
Returns:
list: list of extracted numbers as floats, or empty list if none found
"""
Expand All @@ -100,7 +103,8 @@ def extract_number(text, short_scale=True, ordinals=False, lang=''):
is now common in most English speaking countries.
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
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
Returns:
(int, float or False): The number extracted or False if the input
text contains no numbers
Expand All @@ -112,20 +116,23 @@ def extract_duration(text, lang=''):
""" Convert an english phrase into a number of seconds
Convert things like:
"10 minute"
"2 and a half hours"
"3 days 8 hours 10 minutes and 49 seconds"
* "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
the remainder returned.
As an example, "set a timer for 5 minutes" would return
(300, "set a timer for").
``(300, "set a timer for")``.
Args:
text (str): string containing a duration
lang (str): the BCP-47 code for the language to use, None uses default
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
Returns:
(timedelta, str):
Expand Down Expand Up @@ -199,7 +206,8 @@ def normalize(text, lang='', remove_articles=True):
Args:
text (str): the string to normalize
lang (str): the BCP-47 code for the language to use, None uses default
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
remove_articles (bool): whether to remove articles (like 'a', or
'the'). True by default.
Expand All @@ -218,7 +226,8 @@ def get_gender(word, context="", lang=''):
Args:
word (str): The word to look up
context (str, optional): String containing word, for context
lang (str): the BCP-47 code for the language to use, None uses default
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
Returns:
str: The code "m" (male), "f" (female) or "n" (neutral) for the gender,
Expand All @@ -238,7 +247,8 @@ def is_fractional(input_str, short_scale=True, lang=''):
Args:
input_str (str): the string to check if fractional
short_scale (bool): use short scale if True, long scale if False
lang (str): the BCP-47 code for the language to use, None uses default
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
Returns:
(bool) or (float): False if not a fraction, otherwise the fraction
"""
Expand All @@ -251,7 +261,8 @@ def is_ordinal(input_str, lang=''):
Args:
input_str (str): the string to check if ordinal
lang (str): the BCP-47 code for the language to use, None uses default
lang (str, optional): an optional BCP-47 language code, if omitted
the default language will be used.
Returns:
(bool) or (float): False if not an ordinal, otherwise the number
corresponding to the ordinal
Expand Down

0 comments on commit 49912ba

Please sign in to comment.