Merge branch 'develop' into bittiming

# Conflicts:
#	test/test_util.py

Author: zariiii9003

.github/workflows/ci.yml

@@ -91,10 +91,12 @@ jobs:
       run: |
         pylint --rcfile=.pylintrc \
         can/**.py \
+        can/io \
         setup.py \
-        doc.conf \
+        doc/conf.py \
         scripts/**.py \
-        examples/**.py
+        examples/**.py \
+        can/interfaces/socketcan
 
   format:
     runs-on: ubuntu-latest
@@ -127,7 +129,10 @@ jobs:
         pip install -r doc/doc-requirements.txt
     - name: Build documentation
       run: |
-        python -m sphinx -Wan doc build
+        python -m sphinx -Wan --keep-going doc build
+    - name: Run doctest
+      run: |
+        python -m sphinx -b doctest -W --keep-going doc build
     - uses: actions/upload-artifact@v3
       with:
         name: sphinx-out

.gitignore

@@ -52,6 +52,7 @@ htmlcov/
 .cache
 nosetests.xml
 coverage.xml
+coverage.lcov
 *,cover
 .hypothesis/
 test.*

.pylintrc

@@ -81,7 +81,8 @@ disable=invalid-name,
 # either give multiple identifier separated by comma (,) or put this option
 # multiple time (only on the command line, not in the configuration file where
 # it should appear only once). See also the "--disable" option for examples.
-enable=c-extension-no-member
+enable=c-extension-no-member,
+       useless-suppression,
 
 
 [REPORTS]

can/bus.py

@@ -314,8 +314,10 @@ def stop_all_periodic_tasks(self, remove_tasks: bool = True) -> None:
     def __iter__(self) -> Iterator[Message]:
         """Allow iteration on messages as they are received.
 
-            >>> for msg in bus:
-            ...     print(msg)
+        .. code-block:: python
+
+            for msg in bus:
+                print(msg)
 
 
         :yields:
@@ -352,9 +354,9 @@ def set_filters(
 
         :param filters:
             A iterable of dictionaries each containing a "can_id",
-            a "can_mask", and an optional "extended" key.
+            a "can_mask", and an optional "extended" key::
 
-            >>> [{"can_id": 0x11, "can_mask": 0x21, "extended": False}]
+                [{"can_id": 0x11, "can_mask": 0x21, "extended": False}]
 
             A filter matches, when
             ``<received_can_id> & can_mask == can_id & can_mask``.
@@ -464,7 +466,5 @@ class _SelfRemovingCyclicTask(CyclicSendTaskABC, ABC):
     Only needed for typing :meth:`Bus._periodic_tasks`. Do not instantiate.
     """
 
-    def stop(  # pylint: disable=arguments-differ
-        self, remove_task: bool = True
-    ) -> None:
+    def stop(self, remove_task: bool = True) -> None:
         raise NotImplementedError()

can/exceptions.py

@@ -32,15 +32,21 @@ class CanError(Exception):
 
     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 ...'
+    .. testsetup:: canerror
+
+        from can import CanError, CanOperationError
+
+    .. doctest:: canerror
+
+        >>> # 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

can/interface.py

@@ -8,8 +8,8 @@
 import logging
 from typing import Any, cast, Iterable, Type, Optional, Union, List
 
+from . import util
 from .bus import BusABC
-from .util import load_config, deprecated_args_alias
 from .interfaces import BACKENDS
 from .exceptions import CanInterfaceNotImplementedError
 from .typechecking import AutoDetectedConfig, Channel
@@ -61,6 +61,13 @@ class Bus(BusABC):  # pylint: disable=abstract-method
     Instantiates a CAN Bus of the given ``interface``, falls back to reading a
     configuration file from default locations.
 
+    .. note::
+        Please note that while the arguments provided to this class take precedence
+        over any existing values from configuration, it is possible that other parameters
+        from the configuration may be added to the bus instantiation.
+        This could potentially have unintended consequences. To prevent this,
+        you may use the *ignore_config* parameter to ignore any existing configurations.
+
     :param channel:
         Channel identification. Expected type is backend dependent.
         Set to ``None`` to let it be resolved automatically from the default
@@ -71,8 +78,13 @@ class Bus(BusABC):  # pylint: disable=abstract-method
         Set to ``None`` to let it be resolved automatically from the default
         :ref:`configuration`.
 
-    :param args:
-        ``interface`` specific positional arguments.
+    :param config_context:
+        Extra 'context', that is passed to config sources.
+        This can be used to select a section other than 'default' in the configuration file.
+
+    :param ignore_config:
+        If ``True``, only the given arguments will be used for the bus instantiation. Existing
+        configuration sources will be ignored.
 
     :param kwargs:
         ``interface`` specific keyword arguments.
@@ -88,25 +100,28 @@ class Bus(BusABC):  # pylint: disable=abstract-method
     """
 
     @staticmethod
-    @deprecated_args_alias(bustype="interface")  # Deprecated since python-can 4.2
-    def __new__(  # type: ignore  # pylint: disable=keyword-arg-before-vararg
+    @util.deprecated_args_alias(
+        deprecation_start="4.2.0",
+        deprecation_end="5.0.0",
+        bustype="interface",
+        context="config_context",
+    )
+    def __new__(  # type: ignore
         cls: Any,
         channel: Optional[Channel] = None,
         interface: Optional[str] = None,
-        *args: Any,
+        config_context: Optional[str] = None,
+        ignore_config: bool = False,
         **kwargs: Any,
     ) -> BusABC:
         # figure out the rest of the configuration; this might raise an error
         if interface is not None:
             kwargs["interface"] = interface
         if channel is not None:
             kwargs["channel"] = channel
-        if "context" in kwargs:
-            context = kwargs["context"]
-            del kwargs["context"]
-        else:
-            context = None
-        kwargs = load_config(config=kwargs, context=context)
+
+        if not ignore_config:
+            kwargs = util.load_config(config=kwargs, context=config_context)
 
         # resolve the bus class to use for that interface
         cls = _get_class_for_interface(kwargs["interface"])
@@ -115,17 +130,12 @@ def __new__(  # type: ignore  # pylint: disable=keyword-arg-before-vararg
         del kwargs["interface"]
 
         # make sure the bus can handle this config format
-        if "channel" not in kwargs:
-            raise ValueError("'channel' argument missing")
-        else:
-            channel = kwargs["channel"]
-            del kwargs["channel"]
-
+        channel = kwargs.pop("channel", channel)
         if channel is None:
             # Use the default channel for the backend
-            bus = cls(*args, **kwargs)
+            bus = cls(**kwargs)
         else:
-            bus = cls(channel, *args, **kwargs)
+            bus = cls(channel, **kwargs)
 
         return cast(BusABC, bus)
 

can/interfaces/ixxat/canlib_vcinpl.py

@@ -417,6 +417,8 @@ class IXXATBus(BusABC):
     }
 
     @deprecated_args_alias(
+        deprecation_start="4.0.0",
+        deprecation_end="5.0.0",
         UniqueHardwareId="unique_hardware_id",
         rxFifoSize="rx_fifo_size",
         txFifoSize="tx_fifo_size",

can/interfaces/ixxat/canlib_vcinpl2.py

@@ -417,6 +417,8 @@ class IXXATBus(BusABC):
     """
 
     @deprecated_args_alias(
+        deprecation_start="4.0.0",
+        deprecation_end="5.0.0",
         UniqueHardwareId="unique_hardware_id",
         rxFifoSize="rx_fifo_size",
         txFifoSize="tx_fifo_size",

can/interfaces/kvaser/canlib.py

@@ -662,9 +662,18 @@ def get_stats(self) -> structures.BusStatistics:
 
         Use like so:
 
-        >>> stats = bus.get_stats()
-        >>> print(stats)
-        std_data: 0, std_remote: 0, ext_data: 0, ext_remote: 0, err_frame: 0, bus_load: 0.0%, overruns: 0
+        .. testsetup:: kvaser
+
+            from unittest.mock import Mock
+            from can.interfaces.kvaser.structures import BusStatistics
+            bus = Mock()
+            bus.get_stats = Mock(side_effect=lambda: BusStatistics())
+
+        .. doctest:: kvaser
+
+            >>> stats = bus.get_stats()
+            >>> print(stats)
+            std_data: 0, std_remote: 0, ext_data: 0, ext_remote: 0, err_frame: 0, bus_load: 0.0%, overruns: 0
 
         :returns: bus statistics.
         """