Merge branch 'develop' into improve-linting

Author: felixdivo

.travis.yml

@@ -77,9 +77,6 @@ jobs:
         # -------------
         # mypy checking:
         - mypy
-          --python-version=3.7
-          --ignore-missing-imports
-          --no-implicit-optional
           can/*.py
           can/io/**.py
           scripts/**.py

can/__init__.py

@@ -6,22 +6,24 @@
 """
 
 import logging
-
 from typing import Dict, Any
 
-__version__ = "4.0.0-dev"
+__version__ = "4.0.0-dev.2"
 
 log = logging.getLogger("can")
 
 rc: Dict[str, Any] = dict()
 
-
-class CanError(IOError):
-    """Indicates an error with the CAN network."""
-
-
 from .listener import Listener, BufferedReader, RedirectReader, AsyncBufferedReader
 
+from .exceptions import (
+    CanError,
+    CanInterfaceNotImplementedError,
+    CanInitializationError,
+    CanOperationError,
+    CanTimeoutError,
+)
+
 from .io import Logger, SizedRotatingLogger, Printer, LogReader, MessageSync
 from .io import ASCWriter, ASCReader
 from .io import BLFReader, BLFWriter

can/broadcastmanager.py

@@ -56,6 +56,8 @@ def __init__(
         :param messages:
             The messages to be sent periodically.
         :param period: The rate in seconds at which to send the messages.
+
+        :raises ValueError: If the given messages are invalid
         """
         messages = self._check_and_convert_messages(messages)
 
@@ -74,7 +76,9 @@ def _check_and_convert_messages(
         Performs error checking to ensure that all Messages have the same
         arbitration ID and channel.
 
-        Should be called when the cyclic task is initialized
+        Should be called when the cyclic task is initialized.
+
+        :raises ValueError: If the given messages are invalid
         """
         if not isinstance(messages, (list, tuple)):
             if isinstance(messages, Message):
@@ -115,6 +119,8 @@ def __init__(
         :param duration:
             Approximate duration in seconds to continue sending messages. If
             no duration is provided, the task will continue indefinitely.
+
+        :raises ValueError: If the given messages are invalid
         """
         super().__init__(messages, period)
         self.duration = duration
@@ -139,6 +145,8 @@ def _check_modified_messages(self, messages: Tuple[Message, ...]) -> None:
         cyclic messages hasn't changed.
 
         Should be called when modify_data is called in the cyclic task.
+
+        :raises ValueError: If the given messages are invalid
         """
         if len(self.messages) != len(messages):
             raise ValueError(
@@ -163,6 +171,8 @@ def modify_data(self, messages: Union[Sequence[Message], Message]) -> None:
             Note: The number of new cyclic messages to be sent must be equal
             to the original number of messages originally specified for this
             task.
+
+        :raises ValueError: If the given messages are invalid
         """
         messages = self._check_and_convert_messages(messages)
         self._check_modified_messages(messages)
@@ -190,6 +200,8 @@ def __init__(
         :param count:
         :param initial_period:
         :param subsequent_period:
+
+        :raises ValueError: If the given messages are invalid
         """
         super().__init__(messages, subsequent_period)
         self._channel = channel
@@ -221,6 +233,8 @@ def __init__(
                          error happened on a `bus` while sending `messages`,
                          it shall return either ``True`` or ``False`` depending
                          on desired behaviour of `ThreadBasedCyclicSendTask`.
+
+        :raises ValueError: If the given messages are invalid
         """
         super().__init__(messages, period, duration)
         self.bus = bus

can/bus.py

@@ -31,7 +31,11 @@ class BusABC(metaclass=ABCMeta):
     """The CAN Bus Abstract Base Class that serves as the basis
     for all concrete interfaces.
 
-    This class may be used as an iterator over the received messages.
+    This class may be used as an iterator over the received messages
+    and as a context manager for auto-closing the bus when done using it.
+
+    Please refer to :ref:`errors` for possible exceptions that may be
+    thrown by certain operations on this bus.
     """
 
     #: a string describing the underlying bus and/or channel
@@ -60,6 +64,10 @@ def __init__(
 
         :param dict kwargs:
             Any backend dependent configurations are passed in this dictionary
+
+        :raises ValueError: If parameters are out of range
+        :raises can.CanInterfaceNotImplementedError: If the driver cannot be accessed
+        :raises can.CanInitializationError: If the bus cannot be initialized
         """
         self._periodic_tasks: List[_SelfRemovingCyclicTask] = []
         self.set_filters(can_filters)
@@ -73,10 +81,9 @@ def recv(self, timeout: Optional[float] = None) -> Optional[Message]:
         :param timeout:
             seconds to wait for a message or None to wait indefinitely
 
-        :return:
-            None on timeout or a :class:`Message` object.
-        :raises can.CanError:
-            if an error occurred while reading
+        :return: ``None`` on timeout or a :class:`Message` object.
+
+        :raises can.CanOperationError: If an error occurred while reading
         """
         start = time()
         time_left = timeout
@@ -141,8 +148,7 @@ def _recv_internal(
             2.  a bool that is True if message filtering has already
                 been done and else False
 
-        :raises can.CanError:
-            if an error occurred while reading
+        :raises can.CanOperationError: If an error occurred while reading
         :raises NotImplementedError:
             if the bus provides it's own :meth:`~can.BusABC.recv`
             implementation (legacy implementation)
@@ -165,8 +171,7 @@ def send(self, msg: Message, timeout: Optional[float] = None) -> None:
             Might not be supported by all interfaces.
             None blocks indefinitely.
 
-        :raises can.CanError:
-            if the message could not be sent
+        :raises can.CanOperationError: If an error occurred while sending
         """
         raise NotImplementedError("Trying to write to a readonly bus?")
 
@@ -323,7 +328,7 @@ def filters(self) -> Optional[can.typechecking.CanFilters]:
         return self._filters
 
     @filters.setter
-    def filters(self, filters: Optional[can.typechecking.CanFilters]):
+    def filters(self, filters: Optional[can.typechecking.CanFilters]) -> None:
         self.set_filters(filters)
 
     def set_filters(
@@ -336,7 +341,7 @@ def set_filters(
         messages are matched.
 
         Calling without passing any filters will reset the applied
-        filters to `None`.
+        filters to ``None``.
 
         :param filters:
             A iterable of dictionaries each containing a "can_id",
@@ -421,7 +426,7 @@ def state(self) -> BusState:
         return BusState.ACTIVE
 
     @state.setter
-    def state(self, new_state: BusState):
+    def state(self, new_state: BusState) -> None:
         """
         Set the new state of the hardware
         """

can/exceptions.py

@@ -0,0 +1,97 @@
+"""
+There are several specific :class:`Exception` classes to allow user
+code to react to specific scenarios related to CAN busses::
+
+    Exception (Python standard library)
+     +-- ...
+     +-- CanError (python-can)
+         +-- CanInterfaceNotImplementedError
+         +-- CanInterfaceNotImplementedError
+         +-- CanOperationError
+         +-- CanTimeoutError
+
+Keep in mind that some functions and methods may raise different exceptions.
+For example, validating typical arguments and parameters might result in a
+:class:`ValueError`. This should always be documented for the function at hand.
+"""
+
+from typing import Optional
+
+
+class CanError(Exception):
+    """Base class for all CAN related exceptions.
+
+    If specified, the error code is automatically appended to the message:
+
+    >>> # With an error code (it also works with a specific error):
+    >>> error = CanOperationError(message="Failed to do the thing", error_code=42)
+    >>> str(error)
+    'Failed to do the thing [Error Code 42]'
+    >>>
+    >>> # Missing the error code:
+    >>> plain_error = CanError(message="Something went wrong ...")
+    >>> str(plain_error)
+    'Something went wrong ...'
+
+    :param error_code:
+        An optional error code to narrow down the cause of the fault
+
+    :arg error_code:
+        An optional error code to narrow down the cause of the fault
+    """
+
+    def __init__(
+        self,
+        message: str = "",
+        error_code: Optional[int] = None,
+    ) -> None:
+        self.error_code = error_code
+        super().__init__(
+            message if error_code is None else f"{message} [Error Code {error_code}]"
+        )
+
+
+class CanInterfaceNotImplementedError(CanError, NotImplementedError):
+    """Indicates that the interface is not supported on the current platform.
+
+    Example scenarios:
+      - No interface with that name exists
+      - The interface is unsupported on the current operating system or interpreter
+      - The driver could not be found or has the wrong version
+    """
+
+
+class CanInitializationError(CanError):
+    """Indicates an error the occurred while initializing a :class:`can.BusABC`.
+
+    If initialization fails due to a driver or platform missing/being unsupported,
+    a :class:`can.CanInterfaceNotImplementedError` is raised instead.
+    If initialization fails due to a value being out of range, a :class:`ValueError`
+    is raised.
+
+    Example scenarios:
+      - Try to open a non-existent device and/or channel
+      - Try to use an invalid setting, which is ok by value, but not ok for the interface
+      - The device or other resources are already used
+    """
+
+
+class CanOperationError(CanError):
+    """Indicates an error while in operation.
+
+    Example scenarios:
+      - A call to a library function results in an unexpected return value
+      - An invalid message was received
+      - The driver rejected a message that was meant to be sent
+      - Cyclic redundancy check (CRC) failed
+      - A message remained unacknowledged
+    """
+
+
+class CanTimeoutError(CanError, TimeoutError):
+    """Indicates the timeout of an operation.
+
+    Example scenarios:
+      - Some message could not be sent after the timeout elapsed
+      - No message was read within the given time
+    """