Update docstrings, annotate deprecation, and outline unit tests (#119)

(cherry picked from commit cf8467f)

.github/workflows/unit_tests.yml

@@ -55,7 +55,7 @@ jobs:
           pip install .[extras]
       - name: Install test dependencies
         run: |
-          pip install pytest pytest-timeout pytest-cov
+          pip install pytest pytest-timeout pytest-cov mock
       - name: Run unittests
         run: |
           pytest --cov=ovos_utils --cov-report xml test/unittests

ovos_utils/__init__.py

@@ -23,6 +23,7 @@
 # TODO: Deprecate below imports
 from ovos_utils.file_utils import resolve_ovos_resource_file, resolve_resource_file
 from ovos_utils.network_utils import get_ip, get_external_ip, is_connected_dns, is_connected_http, is_connected
+from ovos_utils.log import LOG
 
 
 class classproperty(property):
@@ -33,6 +34,9 @@ def __get__(self, owner_self, owner_cls):
 
 
 def ensure_mycroft_import():
+    # TODO: Deprecate in 0.1.0
+    LOG.warning("This method is deprecated. Anything depending on `mycroft`"
+                "should install `ovos-core` as a dependency")
     try:
         import mycroft
     except ImportError:
@@ -46,6 +50,9 @@ def ensure_mycroft_import():
 
 
 def get_mycroft_root():
+    # TODO: Deprecate in 0.1.0
+    LOG.warning("This method is deprecated. Code should import from the current"
+                "namespace; other system paths are irrelevant.")
     paths = [
         "/opt/venvs/mycroft-core/lib/python3.7/site-packages/",  # mark1/2
         "/opt/venvs/mycroft-core/lib/python3.4/site-packages/ ",  # old mark1 installs

ovos_utils/bracket_expansion.py

@@ -1,7 +1,8 @@
 import re
+from typing import List
 
 
-def expand_parentheses(sent):
+def expand_parentheses(sent: List[str]) -> List[str]:
     """
     ['1', '(', '2', '|', '3, ')'] -> [['1', '2'], ['1', '3']]
     For example:

ovos_utils/dialog.py

@@ -3,6 +3,7 @@
 import re
 from os.path import join
 from pathlib import Path
+from typing import Optional
 
 from ovos_utils.bracket_expansion import expand_options
 from ovos_utils.file_utils import resolve_resource_file
@@ -103,12 +104,15 @@ def render(self, template_name, context=None, index=None):
         return line
 
 
-def load_dialogs(dialog_dir, renderer=None):
-    """Load all dialog files within the specified directory.
+def load_dialogs(dialog_dir: str,
+                 renderer: Optional[MustacheDialogRenderer] = None) -> \
+        MustacheDialogRenderer:
+    """
+    Load all dialog files within the specified directory.
 
     Args:
         dialog_dir (str): directory that contains dialog files
-
+        renderer (MustacheDialogRenderer): instance to load files with
     Returns:
         a loaded instance of a dialog renderer
     """
@@ -128,8 +132,10 @@ def load_dialogs(dialog_dir, renderer=None):
     return renderer
 
 
-def get_dialog(phrase, lang=None, context=None):
-    """Looks up a resource file for the given phrase.
+def get_dialog(phrase: str, lang: str = None,
+               context: Optional[dict] = None) -> str:
+    """
+    Looks up a resource file for the given phrase.
 
     If no file is found, the requested phrase is returned as the string. This
     will use the default language for translations.
@@ -168,8 +174,10 @@ def get_dialog(phrase, lang=None, context=None):
     return stache.render('template', context)
 
 
-def join_list(items, connector, sep=None, lang=''):
-    """ Join a list into a phrase using the given connector word
+def join_list(items: list, connector: str, sep: Optional[str] = None,
+              lang: Optional[str] = '') -> str:
+    """
+    Join a list into a phrase using the given connector word
     Examples:
         join_list([1,2,3], "and") ->  "1, 2 and 3"
         join_list([1,2,3], "and", ";") ->  "1; 2 and 3"

ovos_utils/enclosure/__init__.py

@@ -2,9 +2,12 @@
 from ovos_utils.fingerprinting import detect_platform, MycroftPlatform
 from enum import Enum
 from os.path import exists
+from typing import Optional
+from ovos_utils.log import LOG
 
 
 class MycroftEnclosures(str, Enum):
+    # TODO: Deprecate in 0.1.0
     PICROFT = "picroft"
     BIGSCREEN = "kde"
     OVOS = "OpenVoiceOS"
@@ -17,7 +20,15 @@ class MycroftEnclosures(str, Enum):
     OTHER = "unknown"
 
 
-def enclosure2rootdir(enclosure=None):
+def enclosure2rootdir(enclosure: MycroftEnclosures = None) -> Optional[str]:
+    """
+    Find the default installed core location for a specific platform.
+    @param enclosure: MycroftEnclosures object to get root path for
+    @return: string default root path
+    """
+    # TODO: Deprecate in 0.1.0
+    LOG.warning("This method is deprecated. Code should import from the current"
+                "namespace; other system paths are irrelevant.")
     enclosure = enclosure or detect_enclosure()
     if enclosure == MycroftEnclosures.OLD_MARK1:
         return MycroftRootLocations.OLD_MARK1
@@ -34,7 +45,14 @@ def enclosure2rootdir(enclosure=None):
     return None
 
 
-def detect_enclosure():
+def detect_enclosure() -> MycroftEnclosures:
+    """
+    Determine which enclosure is present on this file system.
+    @return: MycroftEnclosures object detected
+    """
+    # TODO: Deprecate in 0.1.0
+    LOG.warning("This method is deprecated. Platform-specific code should"
+                "use ovos_utils.fingerprinting.detect_platform directly")
     platform = detect_platform()
     if platform == MycroftPlatform.MARK1:
         if exists(MycroftRootLocations.OLD_MARK1):

ovos_utils/events.py

@@ -7,8 +7,9 @@
 from ovos_utils.messagebus import Message, FakeBus
 
 
-def unmunge_message(message, skill_id):
-    """Restore message keywords by removing the Letterified skill ID.
+def unmunge_message(message: Message, skill_id: str) -> Message:
+    """
+    Restore message keywords by removing the Letterified skill ID.
     Args:
         message (Message): Intent result message
         skill_id (str): skill identifier
@@ -26,8 +27,9 @@ def unmunge_message(message, skill_id):
     return message
 
 
-def get_handler_name(handler):
-    """Name (including class if available) of handler function.
+def get_handler_name(handler) -> str:
+    """
+    Name (including class if available) of handler function.
 
     Args:
         handler (function): Function to be named
@@ -41,8 +43,9 @@ def get_handler_name(handler):
         return handler.__name__
 
 
-def create_wrapper(handler, skill_id, on_start, on_end, on_error):
-    """Create the default skill handler wrapper.
+def create_wrapper(handler, skill_id, on_start, on_end, on_error) -> callable:
+    """
+    Create the default skill handler wrapper.
 
     This wrapper handles things like metrics, reporting handler start/stop
     and errors.
@@ -77,7 +80,7 @@ def wrapper(message):
     return wrapper
 
 
-def create_basic_wrapper(handler, on_error=None):
+def create_basic_wrapper(handler, on_error=None) -> callable:
     """Create the default skill handler wrapper.
 
     This wrapper handles things like metrics, reporting handler start/stop

ovos_utils/file_utils.py

@@ -3,6 +3,8 @@
 import os
 import re
 import tempfile
+from typing import Optional, List
+
 import time
 from os import walk
 from os.path import dirname
@@ -16,8 +18,9 @@
 from ovos_utils.system import search_mycroft_core_location
 
 
-def get_temp_path(*args):
-    """Generate a valid path in the system temp directory.
+def get_temp_path(*args) -> str:
+    """
+    Generate a valid path in the system temp directory.
 
     This method accepts one or more strings as arguments. The arguments are
     joined and returned as a complete path inside the systems temp directory.
@@ -40,9 +43,13 @@ def get_temp_path(*args):
     return path
 
 
-def get_cache_directory(folder):
-    # optional import to use ram for cache
-    # does not work in windows!
+def get_cache_directory(folder: str) -> str:
+    """
+    Get a temporary cache directory, preferably in RAM.
+    Note that Windows will not use RAM.
+    @param folder: base path to use for cache
+    @return: valid cache path
+    """
     path = get_temp_path(folder)
     if os.name != 'nt':
         try:
@@ -56,8 +63,9 @@ def get_cache_directory(folder):
     return path
 
 
-def resolve_ovos_resource_file(res_name):
-    """Convert a resource into an absolute filename.
+def resolve_ovos_resource_file(res_name: str) -> Optional[str]:
+    """
+    Convert a resource into an absolute filename.
     used internally for ovos resources
     """
     # First look for fully qualified file (e.g. a user setting)
@@ -78,8 +86,10 @@ def resolve_ovos_resource_file(res_name):
     return None  # Resource cannot be resolved
 
 
-def resolve_resource_file(res_name, root_path=None, config=None):
-    """Convert a resource into an absolute filename.
+def resolve_resource_file(res_name: str, root_path: Optional[str] = None,
+                          config: Optional[dict] = None) -> Optional[str]:
+    """
+    Convert a resource into an absolute filename.
 
     Resource names are in the form: 'filename.ext'
     or 'path/filename.ext'
@@ -99,6 +109,7 @@ def resolve_resource_file(res_name, root_path=None, config=None):
 
     Args:
         res_name (str): a resource path/name
+        root_path: Optional root path to check
         config (dict): mycroft.conf, to read data directory from
     Returns:
         str: path to resource or None if no resource found
@@ -134,18 +145,19 @@ def resolve_resource_file(res_name, root_path=None, config=None):
     return None  # Resource cannot be resolved
 
 
-def read_vocab_file(path):
-    """ Read voc file.
+def read_vocab_file(path: str) -> List[List[str]]:
+    """
+    Read voc file.
 
-        This reads a .voc file, stripping out empty lines comments and expand
-        parentheses. It returns each line as a list of all expanded
-        alternatives.
+    This reads a .voc file, stripping out empty lines comments and expand
+    parentheses. It returns each line as a list of all expanded
+    alternatives.
 
-        Args:
-            path (str): path to vocab file.
+    Args:
+        path (str): path to vocab file.
 
-        Returns:
-            List of Lists of strings.
+    Returns:
+        List of Lists of strings.
     """
     vocab = []
     with open(path, 'r', encoding='utf8') as voc_file:
@@ -156,8 +168,9 @@ def read_vocab_file(path):
     return vocab
 
 
-def load_regex_from_file(path, skill_id):
-    """Load regex from file
+def load_regex_from_file(path: str, skill_id: str) -> List[str]:
+    """
+    Load regex from file
     The regex is sent to the intent handler using the message bus
 
     Args:
@@ -185,8 +198,9 @@ def load_regex_from_file(path, skill_id):
     return regexes
 
 
-def load_vocabulary(basedir, skill_id):
-    """Load vocabulary from all files in the specified directory.
+def load_vocabulary(basedir: str, skill_id: str) -> dict:
+    """
+    Load vocabulary from all files in the specified directory.
 
     Args:
         basedir (str): path of directory to load from (will recurse)
@@ -207,13 +221,12 @@ def load_vocabulary(basedir, skill_id):
     return vocabs
 
 
-def load_regex(basedir, skill_id):
-    """Load regex from all files in the specified directory.
+def load_regex(basedir: str, skill_id: str) -> List[List[str]]:
+    """
+    Load regex from all files in the specified directory.
 
     Args:
         basedir (str): path of directory to load from
-        bus (messagebus emitter): messagebus instance used to send the vocab to
-                                  the intent service
         skill_id (str): skill identifier
     """
     regexes = []
@@ -224,8 +237,9 @@ def load_regex(basedir, skill_id):
     return regexes
 
 
-def read_value_file(filename, delim):
-    """Read value file.
+def read_value_file(filename: str, delim: str) -> collections.OrderedDict:
+    """
+    Read value file.
 
     The value file is a simple csv structure with a key and value.
 
@@ -252,8 +266,9 @@ def read_value_file(filename, delim):
     return result
 
 
-def read_translated_file(filename, data):
-    """Read a file inserting data.
+def read_translated_file(filename: str, data: dict) -> Optional[List[str]]:
+    """
+    Read a file inserting data.
 
     Args:
         filename (str): file to read

ovos_utils/fingerprinting.py

@@ -150,6 +150,7 @@ def is_mycroft_core():
     except ImportError:
         return False
 
+
 def is_vanilla_mycroft_core():
     return is_mycroft_core() and not is_ovos()