Add typing annotations for can.util

karlding · felixdivo · commit 7bf39285967d · 2019-09-20T13:04:15.000+02:00
This adds typing annotations for functions in can.util.

In addition, this remove the redundant typing information that was
previously in the docstring, since we now have sphinx-autodoc-typehints
to generate the types for the docs from the annotations in the function
signature.

This works towards PEP 561 compatibility.
diff --git a/can/typechecking.py b/can/typechecking.py
@@ -27,3 +27,5 @@
 FileLike = typing.IO[typing.Any]
 StringPathLike = typing.Union[str, "os.PathLike[str]"]
 AcceptedIOType = typing.Optional[typing.Union[FileLike, StringPathLike]]
+
+BusConfig = typing.NewType("BusConfig", dict)
diff --git a/can/util.py b/can/util.py
@@ -2,6 +2,10 @@
 Utilities and configuration file parsing.
 """
 
+from typing import Dict, Optional, Union
+
+from can import typechecking
+
 import json
 import os
 import os.path
@@ -29,7 +33,9 @@
     CONFIG_FILES.extend(["can.ini", os.path.join(os.getenv("APPDATA", ""), "can.ini")])
 
 
-def load_file_config(path=None, section="default"):
+def load_file_config(
+    path: Optional[typechecking.AcceptedIOType] = None, section: str = "default"
+) -> Dict[str, str]:
     """
     Loads configuration from file with following content::
 
@@ -57,7 +63,7 @@ def load_file_config(path=None, section="default"):
     return _config
 
 
-def load_environment_config(context=None):
+def load_environment_config(context: Optional[str] = None) -> Dict[str, str]:
     """
     Loads config dict from environmental variables (if set):
 
@@ -83,20 +89,22 @@ def load_environment_config(context=None):
 
     context_suffix = "_{}".format(context) if context else ""
 
-    config = {}
-
     can_config_key = "CAN_CONFIG" + context_suffix
-    if can_config_key in os.environ:
-        config = json.loads(os.environ.get(can_config_key))
+    config: Dict[str, str] = json.loads(os.environ.get(can_config_key, "{}"))
 
     for key, val in mapper.items():
-        if val in os.environ:
-            config[key] = os.environ.get(val + context_suffix)
+        config_option = os.environ.get(val + context_suffix, None)
+        if config_option:
+            config[key] = config_option
 
     return config
 
 
-def load_config(path=None, config=None, context=None):
+def load_config(
+    path: Optional[typechecking.AcceptedIOType] = None,
+    config=None,
+    context: Optional[str] = None,
+) -> typechecking.BusConfig:
     """
     Returns a dict with configuration details which is loaded from (in this order):
 
@@ -213,26 +221,25 @@ def load_config(path=None, config=None, context=None):
     return config
 
 
-def set_logging_level(level_name=None):
+def set_logging_level(level_name: Optional[str] = None):
     """Set the logging level for the "can" logger.
     Expects one of: 'critical', 'error', 'warning', 'info', 'debug', 'subdebug'
     """
     can_logger = logging.getLogger("can")
 
     try:
-        can_logger.setLevel(getattr(logging, level_name.upper()))
+        can_logger.setLevel(getattr(logging, level_name.upper()))  # type: ignore
     except AttributeError:
         can_logger.setLevel(logging.DEBUG)
     log.debug("Logging set to {}".format(level_name))
 
 
-def len2dlc(length):
+def len2dlc(length: int) -> int:
     """Calculate the DLC from data length.
 
     :param int length: Length in number of bytes (0-64)
 
     :returns: DLC (0-15)
-    :rtype: int
     """
     if length <= 8:
         return length
@@ -242,25 +249,23 @@ def len2dlc(length):
     return 15
 
 
-def dlc2len(dlc):
+def dlc2len(dlc: int) -> int:
     """Calculate the data length from DLC.
 
-    :param int dlc: DLC (0-15)
+    :param dlc: DLC (0-15)
 
     :returns: Data length in number of bytes (0-64)
-    :rtype: int
     """
     return CAN_FD_DLC[dlc] if dlc <= 15 else 64
 
 
-def channel2int(channel):
+def channel2int(channel: Optional[Union[typechecking.Channel]]) -> Optional[int]:
     """Try to convert the channel to an integer.
 
     :param channel:
         Channel string (e.g. can0, CAN1) or integer
 
     :returns: Channel integer or `None` if unsuccessful
-    :rtype: int
     """
     if channel is None:
         return None
