smpclient 4.2.0__tar.gz → 4.3.0__tar.gz

{smpclient-4.2.0 → smpclient-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: smpclient
-Version: 4.2.0
+Version: 4.3.0
 Summary: Simple Management Protocol (SMP) Client for remotely managing MCU firmware
 Home-page: https://github.com/intercreate/smpclient
 License: Apache-2.0
@@ -18,6 +18,7 @@ Requires-Dist: bleak (>=0.22.1,<0.23.0)
 Requires-Dist: intelhex (>=2.3.0,<3.0.0)
 Requires-Dist: pyserial (>=3.5,<4.0)
 Requires-Dist: smp (>=3.1.1,<4.0.0)
+Project-URL: Documentation, https://intercreate.github.io/smpclient
 Project-URL: Repository, https://github.com/intercreate/smpclient
 Description-Content-Type: text/markdown
 
@@ -39,6 +40,11 @@ If you'd like an SMP CLI application instead of a library, then you should try
 
 `smpclient` is [distributed by PyPI](https://pypi.org/project/smpclient/) and can be installed with `poetry`, `pip`, and other dependency managers.
 
+## User Documentation
+
+Documentation is in the source code so that it is available to your editor.
+An online version is generated and available [here](https://intercreate.github.io/smpclient/).
+
 ## Development Quickstart
 
 > Assumes that you've already [setup your development environment](#development-environment-setup).

{smpclient-4.2.0 → smpclient-4.3.0}/README.md

@@ -16,6 +16,11 @@ If you'd like an SMP CLI application instead of a library, then you should try
 
 `smpclient` is [distributed by PyPI](https://pypi.org/project/smpclient/) and can be installed with `poetry`, `pip`, and other dependency managers.
 
+## User Documentation
+
+Documentation is in the source code so that it is available to your editor.
+An online version is generated and available [here](https://intercreate.github.io/smpclient/).
+
 ## Development Quickstart
 
 > Assumes that you've already [setup your development environment](#development-environment-setup).

{smpclient-4.2.0 → smpclient-4.3.0}/pyproject.toml

@@ -7,6 +7,7 @@ authors = [
     "J.P. Hutchins <jp@intercreate.io",
 ]
 repository = "https://github.com/intercreate/smpclient"
+documentation = "https://intercreate.github.io/smpclient"
 readme = "README.md"
 license = "Apache-2.0"
 packages = [{ include = "smpclient" }]
@@ -36,6 +37,14 @@ mypy-extensions = "^1.0.0"
 pytest-asyncio = "^0.23.2"
 types-pyserial = "^3.5.0.11"
 tox = "^4.15.0"
+pydoclint = "^0.5.8"
+
+[tool.poetry.group.doc.dependencies]
+mkdocstrings = { extras = ["python"], version = "^0.26.1" }
+mike = "^2.1.3"
+mkdocs-material = "^9.5.38"
+griffe-inherited-docstrings = "^1.0.1"
+griffe = "^1.3.1"
 
 [tool.black]
 line-length = 100
@@ -52,6 +61,13 @@ skip = [".venv", "dutfirmware", ".tox"]
 disallow_untyped_defs = true
 exclude = ['.venv', 'dutfirmware', '.tox']
 
+[tool.pydoclint]
+style = "google"
+arg-type-hints-in-docstring = false
+allow-init-docstring = true
+check-return-types = false
+check-yield-types = false
+
 [tool.pytest.ini_options]
 norecursedirs = "dutfirmware/*"
 filterwarnings = ["ignore:The --rsyncdir:DeprecationWarning"]

{smpclient-4.2.0 → smpclient-4.3.0}/smpclient/__init__.py

@@ -1,4 +1,27 @@
-"""Simple Management Protocol (SMP) Client."""
+"""Simple Management Protocol (SMP) Client.
+
+This package implements transport layers for the Simple Management Protocol (SMP).
+The SMP Protocol defines common management operations for MCUs like firmware
+updates, file management, configuration, and statistics retrieval.
+
+Additionally, SMP is extensible, allowing for custom commands to be defined to
+meet the specific needs of the product.
+
+### Operating Systems
+
+|   | Windows 11 | Ubuntu | macOS (Arm/x86) |
+|---|------------|-------|-------|
+| Serial (UART, USB, CAN, ...) | ✅ | ✅ | ✅ |
+| Bluetooth Low Energy (BLE)  | ✅ | ✅ | ✅ |
+| UDP (Ethernet, Wi-Fi) | ✅ | ✅ | ✅ |
+
+### Examples
+
+Many usage examples are available on
+[GitHub](https://github.com/intercreate/smpclient/tree/main/examples)
+or in your local clone at `examples/`.
+
+"""
 
 from __future__ import annotations
 
@@ -6,7 +29,7 @@ import asyncio
 import logging
 from hashlib import sha256
 from types import TracebackType
-from typing import AsyncIterator, Final, Tuple, Type
+from typing import AsyncIterator, Final, NoReturn, Tuple, Type
 
 from pydantic import ValidationError
 from smp import header as smpheader
@@ -28,13 +51,51 @@ logger = logging.getLogger(__name__)
 
 
 class SMPClient:
-    def __init__(self, transport: SMPTransport, address: str):
-        """Create a client to the SMP server `address`, using `transport`."""
+    """Create a client to the SMP server `address`, using `transport`.
+
+    This class provides a high-level interface to an SMP server.  Other than
+    the `request` method, all methods are abstractions of common SMP routines,
+    such as uploading a FW image or downloading a file.
+
+    The `request` method is used to send an SMP request to the server and return
+    the response or error.
+
+    Args:
+        transport: the `SMPTransport` to use
+        address: the address of the SMP server, see `smpclient.transport` for details
+
+    Example:
+
+    ```python
+    import asyncio
+    from smpclient import SMPClient
+    from smpclient.requests.os_management import EchoWrite
+    from smpclient.transport.ble import SMPBLETransport
+
+    async def main():
+        async with SMPClient(SMPBLETransport(), "00:11:22:33:44:55") as client:
+            response = await client.request(EchoWrite(d="Hello, World!"))
+
+            if success(response):
+                print(f"Response: {response=}")
+            elif error(response):
+                print(f"Error: {response=}")
+
+    if __name__ == "__main__":
+        asyncio.run(main())
+    ```
+    """
+
+    def __init__(self, transport: SMPTransport, address: str):  # noqa: DOC301
         self._transport: Final = transport
         self._address: Final = address
 
     async def connect(self, timeout_s: float = 5.0) -> None:
-        """Connect to the SMP server."""
+        """Connect to the SMP server.
+
+        Args:
+            timeout_s: the timeout for the connection attempt in seconds
+        """
         await self._transport.connect(self._address, timeout_s)
         await self._initialize()
 
@@ -45,7 +106,53 @@ class SMPClient:
     async def request(
         self, request: SMPRequest[TRep, TEr1, TEr2], timeout_s: float = 120.000
     ) -> TRep | TEr1 | TEr2:
-        """Make an `SMPRequest` to the SMP server."""
+        """Make an `SMPRequest` to the SMP server and return the Response or Error.
+
+        Args:
+            request: the `SMPRequest` to send
+            timeout_s: the timeout for the request in seconds
+
+        Returns:
+            The typed and validated Response or Error
+
+        Raises:
+            TimeoutError: if the request times out
+            SMPBadSequence: if the response sequence does not match the request sequence
+            ValidationError: if the response cannot be parsed as a Response or Error
+
+        Examples:
+
+        Usage:
+
+        ```python
+        response = await client.request(EchoWrite(d="Hello, World!"))
+        if success(response):
+            print(f"Response: {response=}")
+        elif error(response):
+            print(f"Error: {response=}")
+        ```
+
+        Type Safety with Generic Typing:
+
+        ```python
+        response = await client.request(EchoWrite(d="Hello, World!"))
+        reveal_type(response)
+        # Revealed type is 'Union[EchoWriteResponse, EchoWriteErrorV1, EchoWriteErrorV2]'
+        if success(response):
+            reveal_type(response)
+            # Revealed type is 'EchoWriteResponse'
+        elif error(response):
+            reveal_type(response)
+            # Revealed type is 'Union[EchoWriteErrorV1, EchoWriteErrorV2]'
+            if error_v1(response):
+                reveal_type(response)
+                # Revealed type is 'EchoWriteErrorV1'
+            else:
+                reveal_type(response)
+                # Revealed type is 'EchoWriteErrorV2'
+        ```
+
+        """
 
         try:
             async with timeout(timeout_s):
@@ -91,22 +198,29 @@ class SMPClient:
     ) -> AsyncIterator[int]:
         """Iteratively upload an `image` to `slot`, yielding the offset.
 
-        Parameters:
-        - `image`: the `bytes` to upload
-        - `slot`: the slot to upload to (0 for default)
-        - `upgrade`: `True` to mark the image as confirmed.  This is unsafe and
-            can cause a boot-loop that could brick the device.  This setting
-            should be left at the default `False` and the image should be
-            confirmed from within the upgraded application.  Zephyr provides
-            [boot_write_img_confirmed()](https://docs.zephyrproject.org/apidoc/latest/group__mcuboot__api.html#ga95ccc9e1c7460fec16b9ce9ac8ad7a72)
-            for this purpose.
-        - `first_timeout_s`: the timeout for the first `ImageUploadWrite` request
-        - `subsequent_timeout_s`: the timeout for subsequent `ImageUploadWrite` requests
-        - `use_sha`: `True` to include the SHA256 hash of the image in the first
-            packet.
-            - Zephyr's SMP server will fail with `MGMT_ERR.EINVAL` if the
-            MTU is too small to include both the SHA256 and the first 32-bytes
-            of the image.  Increase the MTU or set `use_sha=False` in this case.
+        Args:
+            image: the `bytes` to upload
+            slot: the slot to upload to (0 for default)
+            upgrade: `True` to mark the image as confirmed.  This is unsafe and
+                can cause a boot-loop that could brick the device.  This setting
+                should be left at the default `False` and the image should be
+                confirmed from within the upgraded application.  Zephyr provides
+                [boot_write_img_confirmed()](https://docs.zephyrproject.org/apidoc/latest/group__mcuboot__api.html#ga95ccc9e1c7460fec16b9ce9ac8ad7a72)
+                for this purpose.
+            first_timeout_s: the timeout for the first `ImageUploadWrite` request
+            subsequent_timeout_s: the timeout for subsequent `ImageUploadWrite` requests
+            use_sha: `True` to include the SHA256 hash of the image in the first
+                packet.
+
+                Zephyr's SMP server will fail with `MGMT_ERR.EINVAL` if the
+                MTU is too small to include both the SHA256 and the first 32-bytes
+                of the image.  Increase the MTU or set `use_sha=False` in this case.
+
+        Yields:
+            the offset of the image upload
+
+        Raises:
+            SMPUploadError: if the upload routine fails
         """
 
         response = await self.request(
@@ -131,7 +245,7 @@ class SMPClient:
                 raise SMPUploadError(f"No offset received: {response=}")
             yield response.off
         else:  # pragma: no cover
-            raise Exception("Unreachable")
+            _unreachable()
 
         # send chunks until the SMP server reports that the offset is at the end of the image
         while response.off != len(image):
@@ -155,7 +269,7 @@ class SMPClient:
                     raise SMPUploadError(f"No offset received: {response=}")
                 yield response.off
             else:  # pragma: no cover
-                raise Exception("Unreachable")
+                _unreachable()
 
         logger.info("Upload complete")
 
@@ -172,6 +286,19 @@ class SMPClient:
         file_path: str,
         timeout_s: float = 2.500,
     ) -> AsyncIterator[int]:
+        """Iteratively upload a `file_data` to `file_path`, yielding the offset.
+
+        Args:
+            file_data: the `bytes` to upload
+            file_path: the path to upload to
+            timeout_s: the timeout for each `FileUpload` request
+
+        Yields:
+            int: the offset of the file upload
+
+        Raises:
+            SMPUploadError: if the upload routine fails
+        """
         response = await self.request(
             self._maximize_file_upload_packet(
                 FileUpload(name=file_path, off=0, data=b"", len=len(file_data)),
@@ -187,7 +314,7 @@ class SMPClient:
                 raise SMPUploadError(f"No offset received: {response=}")
             yield response.off
         else:  # pragma: no cover
-            raise Exception("Unreachable")
+            _unreachable()
 
         # send chunks until the SMP server reports that the offset is at the end of the image
         while response.off != len(file_data):
@@ -202,7 +329,7 @@ class SMPClient:
             elif success(response):
                 yield response.off
             else:  # pragma: no cover
-                raise Exception("Unreachable")
+                _unreachable()
 
         logger.info("Upload complete")
 
@@ -211,6 +338,18 @@ class SMPClient:
         file_path: str,
         timeout_s: float = 2.500,
     ) -> bytes:
+        """Download a file from the SMP server.
+
+        Args:
+            file_path: the path to download
+            timeout_s: the timeout for each `FileDownload` request
+
+        Returns:
+            The downloaded file as `bytes`
+
+        Raises:
+            SMPUploadError: if the download routine fails
+        """
         response = await self.request(FileDownload(off=0, name=file_path), timeout_s=timeout_s)
         file_length = 0
 
@@ -221,7 +360,7 @@ class SMPClient:
                 raise SMPUploadError(f"No length received: {response=}")
             file_length = response.len
         else:  # pragma: no cover
-            raise Exception("Unreachable")
+            _unreachable()
 
         file_data = response.data
 
@@ -236,13 +375,15 @@ class SMPClient:
             elif success(response):
                 file_data += response.data
             else:  # pragma: no cover
-                raise Exception("Unreachable")
+                _unreachable()
 
         logger.info("Download complete")
         return file_data
 
     @property
     def address(self) -> str:
+        """The SMP server address."""
+
         return self._address
 
     async def __aenter__(self) -> "SMPClient":
@@ -353,6 +494,10 @@ class SMPClient:
                 elif error(mcumgr_parameters):
                     logger.warning(f"Error reading MCUMgr parameters: {mcumgr_parameters}")
                 else:
-                    raise Exception("Unreachable")
+                    _unreachable()
         except asyncio.TimeoutError:
             logger.warning("Timeout waiting for MCUMgr parameters")
+
+
+def _unreachable() -> NoReturn:
+    raise Exception("Unreachable")

{smpclient-4.2.0 → smpclient-4.3.0}/smpclient/generics.py

@@ -1,4 +1,4 @@
-"""Some Generic helpers for the SMP module."""
+"""Generics and TypeGuards for SMP Requests and Responses."""
 
 from __future__ import annotations
 
@@ -10,8 +10,13 @@ from smp import message as smpmessage
 from typing_extensions import TypeGuard
 
 TEr1 = TypeVar("TEr1", bound=smperror.ErrorV1)
+"""Type of SMP Error V1."""
+
 TEr2 = TypeVar("TEr2", bound=smperror.ErrorV2)
+"""Type of SMP Error V2."""
+
 TRep = TypeVar("TRep", bound=Union[smpmessage.ReadResponse, smpmessage.WriteResponse])
+"""Type of successful SMP Response (ReadResponse or WriteResponse)."""
 
 
 class SMPRequest(Protocol[TRep, TEr1, TEr2]):
@@ -43,20 +48,48 @@ class SMPRequest(Protocol[TRep, TEr1, TEr2]):
 
 
 def error_v1(response: smperror.ErrorV1 | TEr2 | TRep) -> TypeGuard[smperror.ErrorV1]:
-    """`TypeGuard` that returns `True` if the `response` is an `ErrorV1`."""
+    """`TypeGuard` that returns `True` if the `response` is an `ErrorV1`.
+
+    Args:
+        response: The response to check.
+
+    Returns:
+        `True` if the `response` is an `ErrorV1`.
+    """
     return response.RESPONSE_TYPE == smpmessage.ResponseType.ERROR_V1
 
 
 def error_v2(response: smperror.ErrorV1 | TEr2 | TRep) -> TypeGuard[TEr2]:
-    """`TypeGuard` that returns `True` if the `response` is an `ErrorV2`."""
+    """`TypeGuard` that returns `True` if the `response` is an `ErrorV2`.
+
+    Args:
+        response: The response to check.
+
+    Returns:
+        `True` if the `response` is an `ErrorV2`.
+    """
     return response.RESPONSE_TYPE == smpmessage.ResponseType.ERROR_V2
 
 
 def error(response: smperror.ErrorV1 | TEr2 | TRep) -> TypeGuard[smperror.ErrorV1 | TEr2]:
-    """`TypeGuard` that returns `True` if the `response` is an `ErrorV1` or `ErrorV2`."""
+    """`TypeGuard` that returns `True` if the `response` is an `ErrorV1` or `ErrorV2`.
+
+    Args:
+        response: The response to check.
+
+    Returns:
+        `True` if the `response` is an `ErrorV1` or `ErrorV2`.
+    """
     return error_v1(response) or error_v2(response)
 
 
 def success(response: smperror.ErrorV1 | TEr2 | TRep) -> TypeGuard[TRep]:
-    """`TypeGuard` that returns `True` if the `response` is a successful `Response`."""
+    """`TypeGuard` that returns `True` if the `response` is a successful `Response`.
+
+    Args:
+        response: The response to check.
+
+    Returns:
+        `True` if the `response` is a successful `Response`.
+    """
     return response.RESPONSE_TYPE == smpmessage.ResponseType.SUCCESS

{smpclient-4.2.0 → smpclient-4.3.0}/smpclient/transport/__init__.py

@@ -6,7 +6,7 @@ from typing import Protocol
 
 
 class SMPTransportDisconnected(Exception):
-    ...
+    """Raised when the SMP transport is disconnected."""
 
 
 class SMPTransport(Protocol):
@@ -14,22 +14,45 @@ class SMPTransport(Protocol):
     """The SMP server transport buffer size, in 8-bit bytes."""
 
     async def connect(self, address: str, timeout_s: float) -> None:  # pragma: no cover
-        """Connect the `SMPTransport`."""
+        """Connect the `SMPTransport`.
+
+        Args:
+            address: The SMP server address.
+            timeout_s: The connection timeout in seconds."""
 
     async def disconnect(self) -> None:  # pragma: no cover
         """Disconnect the `SMPTransport`."""
 
     async def send(self, data: bytes) -> None:  # pragma: no cover
-        """Send the encoded `SMPRequest` `data`."""
+        """Send the encoded `SMPRequest` `data`.
+
+        Args:
+            data: The encoded `SMPRequest`.
+        """
 
     async def receive(self) -> bytes:  # pragma: no cover
-        """Receive the decoded `SMPResponse`."""
+        """Receive the decoded `SMPResponse` data.
+
+        Returns:
+            The `SMPResponse` bytes.
+        """
 
     async def send_and_receive(self, data: bytes) -> bytes:  # pragma: no cover
-        """Send the encoded `SMPRequest` `data` and receive the decoded `SMPResponse`."""
+        """Send the encoded `SMPRequest` `data` and receive the decoded `SMPResponse`.
+
+        Args:
+            data: The encoded `SMPRequest`.
+
+        Returns:
+            The `SMPResponse` bytes.
+        """
 
     def initialize(self, smp_server_transport_buffer_size: int) -> None:  # pragma: no cover
-        """Initialize the `SMPTransport` with the server transport buffer size."""
+        """Initialize the `SMPTransport` with the server transport buffer size.
+
+        Args:
+            smp_server_transport_buffer_size: The SMP server transport buffer size, in 8-bit bytes.
+        """
         self._smp_server_transport_buffer_size = smp_server_transport_buffer_size
 
     @property

{smpclient-4.2.0 → smpclient-4.3.0}/smpclient/transport/_udp_client.py

@@ -22,9 +22,11 @@ class UDPClient:
     async def connect(self, remote_addr: Addr, _local_addr: Addr | None = None) -> None:
         """Create a UDP connection to the given `Addr`.
 
-        Parameters:
-        - remote_addr: The remote address to connect to.
-        - _local_addr: For unit tests only!  The local address to connect from.
+        Args:
+            remote_addr: The remote address to connect to.
+            _local_addr: For unit tests only!  The local address to connect from.
+
+        Example:
 
         ```python
 
@@ -44,12 +46,19 @@ class UDPClient:
 
         This does not block; it buffers the data and arranges for it to be sent
         out asynchronously.
+
+        Args:
+            data: The data to send.
         """
 
         self._transport.sendto(data)
 
     async def receive(self) -> bytes:
-        """Receive data from the transport."""
+        """Receive data from the transport.
+
+        Returns:
+            bytes: The data received
+        """
 
         return await self._protocol.receive_queue.get()
 

{smpclient-4.2.0 → smpclient-4.3.0}/smpclient/transport/ble.py

@@ -51,21 +51,23 @@ UUID_PATTERN: Final = re.compile(
 
 
 class SMPBLETransportException(SMPClientException):
-    ...
+    """Base class for SMP BLE transport exceptions."""
 
 
 class SMPBLETransportDeviceNotFound(SMPBLETransportException):
-    ...
+    """Raised when a BLE device is not found."""
 
 
 class SMPBLETransportNotSMPServer(SMPBLETransportException):
-    ...
+    """Raised when the SMP characteristic UUID is not found."""
 
 
 logger = logging.getLogger(__name__)
 
 
 class SMPBLETransport(SMPTransport):
+    """A Bluetooth Low Energy (BLE) SMPTransport."""
+
     def __init__(self) -> None:
         self._buffer = bytearray()
         self._notify_condition = asyncio.Condition()

{smpclient-4.2.0 → smpclient-4.3.0}/smpclient/transport/serial.py

@@ -1,4 +1,7 @@
-"""A serial SMPTransport."""
+"""A serial SMPTransport.
+
+In addition to UART, this transport can be used with USB CDC ACM and CAN.
+"""
 
 from __future__ import annotations
 
@@ -66,7 +69,7 @@ class SMPSerialTransport(SMPTransport):
             self.state = SMPSerialTransport._ReadBuffer.State.SER
             """The state of the read buffer."""
 
-    def __init__(
+    def __init__(  # noqa: DOC301
         self,
         max_smp_encoded_frame_size: int = 256,
         line_length: int = 128,
@@ -85,24 +88,24 @@ class SMPSerialTransport(SMPTransport):
     ) -> None:
         """Initialize the serial transport.
 
-        Parameters:
-        - `max_smp_encoded_frame_size`: The maximum size of an encoded SMP
-            frame.  The SMP server needs to have a buffer large enough to
-            receive the encoded frame packets and to store the decoded frame.
-        - `line_length`: The maximum SMP packet size.
-        - `line_buffers`: The number of line buffers in the serial buffer.
-        - `baudrate`: The baudrate of the serial connection.  OK to ignore for
-            USB CDC ACM.
-        - `bytesize`: The number of data bits.
-        - `parity`: The parity setting.
-        - `stopbits`: The number of stop bits.
-        - `timeout`: The read timeout.
-        - `xonxoff`: Enable software flow control.
-        - `rtscts`: Enable hardware (RTS/CTS) flow control.
-        - `write_timeout`: The write timeout.
-        - `dsrdtr`: Enable hardware (DSR/DTR) flow control.
-        - `inter_byte_timeout`: The inter-byte timeout.
-        - `exclusive`: The exclusive access timeout.
+        Args:
+            max_smp_encoded_frame_size: The maximum size of an encoded SMP
+                frame.  The SMP server needs to have a buffer large enough to
+                receive the encoded frame packets and to store the decoded frame.
+            line_length: The maximum SMP packet size.
+            line_buffers: The number of line buffers in the serial buffer.
+            baudrate: The baudrate of the serial connection.  OK to ignore for
+                USB CDC ACM.
+            bytesize: The number of data bits.
+            parity: The parity setting.
+            stopbits: The number of stop bits.
+            timeout: The read timeout.
+            xonxoff: Enable software flow control.
+            rtscts: Enable hardware (RTS/CTS) flow control.
+            write_timeout: The write timeout.
+            dsrdtr: Enable hardware (DSR/DTR) flow control.
+            inter_byte_timeout: The inter-byte timeout.
+            exclusive: The exclusive access timeout.
 
         """
         if max_smp_encoded_frame_size < line_length * line_buffers:

{smpclient-4.2.0 → smpclient-4.3.0}/smpclient/transport/udp.py

@@ -1,4 +1,4 @@
-"""A UDP SMPTransport."""
+"""A UDP SMPTransport for Network connections like Wi-Fi or Ethernet."""
 
 import asyncio
 import logging
@@ -16,6 +16,11 @@ logger = logging.getLogger(__name__)
 
 class SMPUDPTransport(SMPTransport):
     def __init__(self, mtu: int = 1500) -> None:
+        """Initialize the SMP UDP transport.
+
+        Args:
+            mtu: The Maximum Transmission Unit (MTU) in 8-bit bytes.
+        """
         self._mtu = mtu
 
         self._client: Final = UDPClient()