fixed docstring formatting, fixed Logger type for Sphinx, Sphinx version to latest

Author: askpatrickw

.github/workflows/build.yml

@@ -42,9 +42,9 @@ jobs:
       # (e.g. - apt-get: gettext, etc; pip: circuitpython-build-tools, requirements.txt; etc.)
       run: |
         source actions-ci/install.sh
-    - name: Pip install Sphinx 4.3.2, pre-commit
+    - name: Pip install Sphinx, pre-commit
       run: |
-        pip install --force-reinstall Sphinx==4.3.2 sphinx-rtd-theme pre-commit
+        pip install --force-reinstall Sphinx sphinx-rtd-theme pre-commit
     - name: Library version
       run: git describe --dirty --always --tags
     - name: Pre-commit hooks

README.rst

@@ -63,8 +63,8 @@ To create an Azure IoT Hub instance or an Azure IoT Central app, you will need a
 
 - If you are not a student, head to `aka.ms/FreeAz <https://aka.ms/FreeAz>`_ and sign up to get $200 of credit for 30 days, as well as free tiers of a load of services. You will need a credit card for validation only, your card will not be charged.
 
-ESP32SPI Networking
-===================
+ESP32 AirLift Networking
+========================
 
 To use this library, you will need to create an ESP32_SPI WifiManager, connected to WiFi. You will also need to set the current time, as this is used to generate time-based authentication keys. One way to do this is via the `Adafruit CircuitPython NTP <https://github.com/adafruit/Adafruit_CircuitPython_NTP>`_ library with the following code:
 
@@ -79,7 +79,7 @@ To use this library, you will need to create an ESP32_SPI WifiManager, connected
 
 Native Networking
 =================
-To use this library, with boards that have native networking support, you need to be connected to a network. You will also need to set the current time, as this is used to generate time-based authentication keys. One way to do this is by using the `Adafruit IoT Time Service <https://io.adafruit.com/api/docs/#time>`_ via the `Adafruit Requests library <https://github.com/adafruit/Adafruit_CircuitPython_Requests>`_ with the following code:
+To use this library, with boards that have native networking support, you need to be connected to a network. You will also need to set the current time, as this is used to generate time-based authentication keys. One way to do this is by using the `Adafruit IoT Time API <https://io.adafruit.com/api/docs/#time>`_ via the `Adafruit Requests library <https://github.com/adafruit/Adafruit_CircuitPython_Requests>`_ with the following code:
 
 .. code-block:: python
 

adafruit_azureiot/device_registration.py

@@ -53,6 +53,7 @@ def __init__(
         logger: Logger = None,
     ):
         """Creates an instance of the device registration service
+
         :param socket: The network socket
         :param str id_scope: The ID scope of the device to register
         :param str device_id: The device ID of the device to register
@@ -163,6 +164,7 @@ def register_device(self, expiry: int) -> str:
         """
         Registers the device with the IoT Central device registration service.
         Returns the hostname of the IoT hub to use over MQTT
+
         :param int expiry: The expiry time for the registration
         :returns: The underlying IoT Hub that this device should connect to
         :rtype: str

adafruit_azureiot/iot_error.py

@@ -20,6 +20,7 @@ class IoTError(Exception):
 
     def __init__(self, message: str):
         """Create the IoT Error
+
         :param str message: The error message
         """
         super().__init__(message)

adafruit_azureiot/iot_mqtt.py

@@ -19,6 +19,7 @@
 
 import adafruit_minimqtt.adafruit_minimqtt as MQTT
 import adafruit_logging as logging
+from adafruit_logging import Logger
 
 from .iot_error import IoTError
 from .keys import compute_derived_symmetric_key
@@ -31,6 +32,7 @@ class IoTResponse:
 
     def __init__(self, code: int, message: str):
         """Creates an IoT Response object
+
         :param int code: The HTTP response code for this method call, for example 200 if the method was handled successfully
         :param str message: The HTTP response message for this method call
         """
@@ -43,17 +45,20 @@ class IoTMQTTCallback:
 
     def message_sent(self, data: str) -> None:
         """Called when a message is sent to the cloud
+
         :param str data: The data send with the message
         """
 
     def connection_status_change(self, connected: bool) -> None:
         """Called when the connection status changes
+
         :param bool connected: True if the device is connected, otherwise false
         """
 
     # pylint: disable=W0613, R0201
     def direct_method_invoked(self, method_name: str, payload: str) -> IoTResponse:
         """Called when a direct method is invoked
+
         :param str method_name: The name of the method that was invoked
         :param str payload: The payload with the message
         :returns: A response with a code and status to show if the method was correctly handled
@@ -64,6 +69,7 @@ def direct_method_invoked(self, method_name: str, payload: str) -> IoTResponse:
     # pylint: disable=C0103
     def cloud_to_device_message_received(self, body: str, properties: dict) -> None:
         """Called when a cloud to device message is received
+
         :param str body: The body of the message
         :param dict properties: The propreties sent with the mesage
         """
@@ -72,6 +78,7 @@ def device_twin_desired_updated(
         self, desired_property_name: str, desired_property_value, desired_version: int
     ) -> None:
         """Called when the device twin desired properties are updated
+
         :param str desired_property_name: The name of the desired property that was updated
         :param desired_property_value: The value of the desired property that was updated
         :param int desired_version: The version of the desired property that was updated
@@ -84,6 +91,7 @@ def device_twin_reported_updated(
         reported_version: int,
     ) -> None:
         """Called when the device twin reported values are updated
+
         :param str reported_property_name: The name of the reported property that was updated
         :param reported_property_value: The value of the reported property that was updated
         :param int reported_version: The version of the reported property that was updated
@@ -319,17 +327,18 @@ def __init__(
         device_id: str,
         device_sas_key: str,
         token_expires: int = 21600,
-        logger: logging = None,
+        logger: Logger = None,
     ):
         """Create the Azure IoT MQTT client
+
         :param IoTMQTTCallback callback: A callback class
         :param socket: The socket to communicate over
         :param iface: The network interface to communicate over
         :param str hostname: The hostname of the MQTT broker to connect to, get this by registering the device
         :param str device_id: The device ID of the device to register
         :param str device_sas_key: The primary or secondary key of the device to register
         :param int token_expires: The number of seconds till the token expires, defaults to 6 hours
-        :param adafruit_logging logger: The logger
+        :param Logger logger: The logger
         """
         self._callback = callback
         self._socket = socket
@@ -372,6 +381,7 @@ def _subscribe_to_twin_topics(self):
 
     def connect(self) -> bool:
         """Connects to the MQTT broker
+
         :returns: True if the connection is successful, otherwise False
         :rtype: bool
         """
@@ -426,6 +436,7 @@ def reconnect(self) -> None:
 
     def is_connected(self) -> bool:
         """Gets if there is an open connection to the MQTT broker
+
         :returns: True if there is an open connection, False if not
         :rtype: bool
         """
@@ -443,6 +454,7 @@ def send_device_to_cloud_message(
         self, message, system_properties: dict = None
     ) -> None:
         """Send a device to cloud message from this device to Azure IoT Hub
+
         :param message: The message data as a JSON string or a dictionary
         :param system_properties: System properties to send with the message
         :raises: ValueError if the message is not a string or dictionary
@@ -472,6 +484,7 @@ def send_device_to_cloud_message(
 
     def send_twin_patch(self, patch) -> None:
         """Send a patch for the reported properties of the device twin
+
         :param patch: The patch as a JSON string or a dictionary
         :raises: IoTError if the data is not a string or dictionary
         :raises RuntimeError: if the internet connection is not responding or is unable to connect

adafruit_azureiot/iotcentral_device.py

@@ -15,6 +15,7 @@
 import json
 import time
 import adafruit_logging as logging
+from adafruit_logging import Logger
 from .device_registration import DeviceRegistration
 from .iot_error import IoTError
 from .iot_mqtt import IoTMQTT, IoTMQTTCallback, IoTResponse
@@ -25,6 +26,7 @@ class IoTCentralDevice(IoTMQTTCallback):
 
     def connection_status_change(self, connected: bool) -> None:
         """Called when the connection status changes
+
         :param bool connected: True if the device is connected, otherwise false
         """
         if self.on_connection_status_changed is not None:
@@ -34,6 +36,7 @@ def connection_status_change(self, connected: bool) -> None:
     # pylint: disable=W0613, R0201
     def direct_method_called(self, method_name: str, payload: str) -> IoTResponse:
         """Called when a direct method is invoked
+
         :param str method_name: The name of the method that was invoked
         :param str payload: The payload with the message
         :returns: A response with a code and status to show if the method was correctly handled
@@ -49,6 +52,7 @@ def device_twin_desired_updated(
         self, desired_property_name: str, desired_property_value, desired_version: int
     ) -> None:
         """Called when the device twin desired properties are updated
+
         :param str desired_property_name: The name of the desired property that was updated
         :param desired_property_value: The value of the desired property that was updated
         :param int desired_version: The version of the desired property that was updated
@@ -69,6 +73,7 @@ def device_twin_reported_updated(
         reported_version: int,
     ) -> None:
         """Called when the device twin reported values are updated
+
         :param str reported_property_name: The name of the reported property that was updated
         :param reported_property_value: The value of the reported property that was updated
         :param int reported_version: The version of the reported property that was updated
@@ -88,16 +93,17 @@ def __init__(
         device_id: str,
         device_sas_key: str,
         token_expires: int = 21600,
-        logger: logging = None,
+        logger: Logger = None,
     ):
         """Create the Azure IoT Central device client
+
         :param socket: The network socket
         :param iface: The network interface
         :param str id_scope: The ID Scope of the device in IoT Central
         :param str device_id: The device ID of the device in IoT Central
         :param str device_sas_key: The primary or secondary key of the device in IoT Central
         :param int token_expires: The number of seconds till the token expires, defaults to 6 hours
-        :param adafruit_logging logger: The logger
+        :param Logger logger: The logger
         """
         self._socket = socket
         self._iface = iface
@@ -132,6 +138,7 @@ def property_changed(_property_name: str, property_value, version: int) -> None
 
     def connect(self) -> None:
         """Connects to Azure IoT Central
+
         :raises DeviceRegistrationError: if the device cannot be registered successfully
         :raises RuntimeError: if the internet connection is not responding or is unable to connect
         """
@@ -166,6 +173,7 @@ def connect(self) -> None:
 
     def disconnect(self) -> None:
         """Disconnects from the MQTT broker
+
         :raises IoTError: if there is no open connection to the MQTT broker
         """
         if self._mqtt is None:
@@ -182,13 +190,15 @@ def reconnect(self) -> None:
 
     def is_connected(self) -> bool:
         """Gets if there is an open connection to the MQTT broker
+
         :returns: True if there is an open connection, False if not
         :rtype: bool
         """
         return self._mqtt.is_connected() if self._mqtt is not None else False
 
     def loop(self) -> None:
         """Listens for MQTT messages
+
         :raises IoTError: if there is no open connection to the MQTT broker
         """
         if self._mqtt is None:
@@ -198,6 +208,7 @@ def loop(self) -> None:
 
     def send_property(self, property_name: str, value) -> None:
         """Updates the value of a writable property
+
         :param str property_name: The name of the property to write to
         :param value: The value to set on the property
         :raises IoTError: if there is no open connection to the MQTT broker
@@ -211,6 +222,7 @@ def send_property(self, property_name: str, value) -> None:
 
     def send_telemetry(self, data) -> None:
         """Sends telemetry to the IoT Central app
+
         :param data: The telemetry data to send
         :raises IoTError: if there is no open connection to the MQTT broker
         """

adafruit_azureiot/iothub_device.py

@@ -19,6 +19,7 @@
 
 import json
 import adafruit_logging as logging
+from adafruit_logging import Logger
 from .iot_error import IoTError
 from .iot_mqtt import IoTMQTT, IoTMQTTCallback, IoTResponse
 
@@ -65,6 +66,7 @@ class IoTHubDevice(IoTMQTTCallback):
 
     def connection_status_change(self, connected: bool) -> None:
         """Called when the connection status changes
+
         :param bool connected: True if the device is connected, otherwise false
         """
         if self._on_connection_status_changed is not None:
@@ -74,6 +76,7 @@ def connection_status_change(self, connected: bool) -> None:
     # pylint: disable=W0613, R0201
     def direct_method_invoked(self, method_name: str, payload: str) -> IoTResponse:
         """Called when a direct method is invoked
+
         :param str method_name: The name of the method that was invoked
         :param str payload: The payload with the message
         :returns: A response with a code and status to show if the method was correctly handled
@@ -88,6 +91,7 @@ def direct_method_invoked(self, method_name: str, payload: str) -> IoTResponse:
     # pylint: disable=C0103
     def cloud_to_device_message_received(self, body: str, properties: dict) -> None:
         """Called when a cloud to device message is received
+
         :param str body: The body of the message
         :param dict properties: The propreties sent with the mesage
         """
@@ -102,6 +106,7 @@ def device_twin_desired_updated(
         desired_version: int,
     ) -> None:
         """Called when the device twin desired properties are updated
+
         :param str desired_property_name: The name of the desired property that was updated
         :param desired_property_value: The value of the desired property that was updated
         :param int desired_version: The version of the desired property that was updated
@@ -119,6 +124,7 @@ def device_twin_reported_updated(
         reported_version: int,
     ) -> None:
         """Called when the device twin reported values are updated
+
         :param str reported_property_name: The name of the reported property that was updated
         :param reported_property_value: The value of the reported property that was updated
         :param int reported_version: The version of the reported property that was updated
@@ -135,14 +141,15 @@ def __init__(
         iface,
         device_connection_string: str,
         token_expires: int = 21600,
-        logger: logging = None,
+        logger: Logger = None,
     ):
         """Create the Azure IoT Central device client
+
         :param socket: The network socket
         :param iface: The network interface
         :param str device_connection_string: The Iot Hub device connection string
         :param int token_expires: The number of seconds till the token expires, defaults to 6 hours
-        :param adafruit_logging logger: The logger
+        :param Logger logger: The logger
         """
         self._socket = socket
         self._iface = iface
@@ -286,6 +293,7 @@ def device_twin_reported_updated(reported_property_name: str, reported_property_
 
     def connect(self) -> None:
         """Connects to Azure IoT Hub
+
         :raises RuntimeError: if the internet connection is not responding or is unable to connect
         """
         self._mqtt = IoTMQTT(
@@ -308,6 +316,7 @@ def connect(self) -> None:
 
     def loop(self) -> None:
         """Listens for MQTT messages
+
         :raises IoTError: if there is no open connection to the MQTT broker
         """
         if self._mqtt is None:
@@ -317,6 +326,7 @@ def loop(self) -> None:
 
     def disconnect(self) -> None:
         """Disconnects from the MQTT broker
+
         :raises IoTError: if there is no open connection to the MQTT broker
         """
         if self._mqtt is None:
@@ -333,6 +343,7 @@ def reconnect(self) -> None:
 
     def is_connected(self) -> bool:
         """Gets if there is an open connection to the MQTT broker
+
         :returns: True if there is an open connection, False if not
         :rtype: bool
         """
@@ -342,6 +353,7 @@ def send_device_to_cloud_message(
         self, message: Union[str, dict], system_properties: dict = None
     ) -> None:
         """Send a device to cloud message from this device to Azure IoT Hub
+
         :param message: The message data as a JSON string or a dictionary
         :param system_properties: System properties to send with the message
         :raises: ValueError if the message is not a string or dictionary
@@ -354,6 +366,7 @@ def send_device_to_cloud_message(
 
     def update_twin(self, patch: Union[str, dict]) -> None:
         """Updates the reported properties in the devices device twin
+
         :param patch: The JSON patch to apply to the device twin reported properties
         """
         if self._mqtt is None: