mycroft.util package¶
The mycroft.util package includes functions for common operations such as playing audio files, parsting and creating natural text as well as many components used internally in Mycroft such as cache directory lookup, path resolution. etc.
Below _some_ of the functions that are of interest to skill developers are listed.
LOG¶
-
mycroft.util.
LOG
(name)[source]¶ Custom logger class that acts like logging.Logger The logger name is automatically generated by the module of the caller
- Usage:
>>> LOG.debug('My message: %s', debug_str) 13:12:43.673 - :<module>:1 - DEBUG - My message: hi >>> LOG('custom_name').debug('Another message') 13:13:10.462 - custom_name - DEBUG - Another message
play_wav¶
-
mycroft.util.
play_wav
(uri, environment=None)[source]¶ Play a wav-file.
This will use the application specified in the mycroft config and play the uri passed as argument. The function will return directly and play the file in the background.
- Parameters
uri – uri to play
environment (dict) – optional environment for the subprocess call
Returns: subprocess.Popen object or None if operation failed
play_mp3¶
-
mycroft.util.
play_mp3
(uri, environment=None)[source]¶ Play a mp3-file.
This will use the application specified in the mycroft config and play the uri passed as argument. The function will return directly and play the file in the background.
- Parameters
uri – uri to play
environment (dict) – optional environment for the subprocess call
Returns: subprocess.Popen object or None if operation failed
play_ogg¶
-
mycroft.util.
play_ogg
(uri, environment=None)[source]¶ Play an ogg-file.
This will use the application specified in the mycroft config and play the uri passed as argument. The function will return directly and play the file in the background.
- Parameters
uri – uri to play
environment (dict) – optional environment for the subprocess call
Returns: subprocess.Popen object, or None if operation failed
extract_datetime¶
-
mycroft.util.
extract_datetime
(text, anchorDate=None, lang=None, default_time=None)[source]¶ Extracts date and time information from a sentence.
Parses many of the common ways that humans express dates and times, including relative dates like “5 days from today”, “tomorrow’, and “Tuesday”.
- Vague terminology are given arbitrary values, like:
morning = 8 AM
afternoon = 3 PM
evening = 7 PM
If a time isn’t supplied or implied, the function defaults to 12 AM :param text: the text to be interpreted :type text: str :param anchorDate: the date to be used for
relative dating (for example, what does “tomorrow” mean?). Defaults to the current local date/time.
- Parameters
lang (str) – the BCP-47 code for the language to use, None uses default
default_time (datetime.time) – time to use if none was found in the input string.
- Returns
- ‘datetime’ is the extracted date
as a datetime object in the user’s local timezone. ‘leftover_string’ is the original phrase with all date and time related keywords stripped out. See examples for further clarification Returns ‘None’ if no date or time related text is found.
- Return type
[
datetime
,str
]
Examples
>>> extract_datetime( ... "What is the weather like the day after tomorrow?", ... datetime(2017, 06, 30, 00, 00) ... ) [datetime.datetime(2017, 7, 2, 0, 0), 'what is weather like'] >>> extract_datetime( ... "Set up an appointment 2 weeks from Sunday at 5 pm", ... datetime(2016, 02, 19, 00, 00) ... ) [datetime.datetime(2016, 3, 6, 17, 0), 'set up appointment'] >>> extract_datetime( ... "Set up an appointment", ... datetime(2016, 02, 19, 00, 00) ... ) None
extract_number¶
-
mycroft.util.
extract_number
(text, short_scale=True, ordinals=False, lang=None)[source]¶ Takes in a string and extracts a number. :param text: the string to extract a number from :type text: str :param short_scale: Use “short scale” or “long scale” for large
numbers – over a million. The default is short scale, which is now common in most English speaking countries. See https://en.wikipedia.org/wiki/Names_of_large_numbers
- Parameters
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
- The number extracted or False if the input
text contains no numbers
- Return type
(int, float or False)
normalize¶
-
mycroft.util.
normalize
(text, lang=None, remove_articles=True)[source]¶ Prepare a string for parsing This function prepares the given text for parsing by making numbers consistent, getting rid of contractions, etc. :param text: the string to normalize :type text: str :param lang: the BCP-47 code for the language to use, None uses default :type lang: str :param remove_articles: whether to remove articles (like ‘a’, or
‘the’). True by default.
- Returns
The normalized string.
- Return type
(str)
nice_number¶
-
mycroft.util.
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)
resolve_resource_file¶
-
mycroft.util.
resolve_resource_file
(res_name)[source]¶ Convert a resource into an absolute filename.
Resource names are in the form: ‘filename.ext’ or ‘path/filename.ext’
The system wil look for ~/.mycroft/res_name first, and if not found will look at /opt/mycroft/res_name, then finally it will look for res_name in the ‘mycroft/res’ folder of the source code package.
Example: With mycroft running as the user ‘bob’, if you called
resolve_resource_file(‘snd/beep.wav’)
it would return either ‘/home/bob/.mycroft/snd/beep.wav’ or ‘/opt/mycroft/snd/beep.wav’ or ‘…/mycroft/res/snd/beep.wav’, where the ‘…’ is replaced by the path where the package has been installed.
- Parameters
res_name (str) – a resource path/name
- Returns
(str) path to resource or None if no resource found
get_cache_directory¶
-
mycroft.util.
get_cache_directory
(domain=None)[source]¶ Get a directory for caching data.
This directory can be used to hold temporary caches of data to speed up performance. This directory will likely be part of a small RAM disk and may be cleared at any time. So code that uses these cached files must be able to fallback and regenerate the file.
- Parameters
domain (str) – The cache domain. Basically just a subdirectory.
- Returns
(str) a path to the directory where you can cache data