Lint docstrings (#137)

* Add requirements

* Fix docstrings in matter server

* Fix docstrings in scripts

Author: MartinHjelmare

main.py

@@ -1,3 +1,4 @@
+"""Run the Matter Server."""
 import sys
 
 from matter_server.server.__main__ import main

matter_server/__init__.py

@@ -0,0 +1 @@
+"""Provide the Matter Server including both a client and server."""

matter_server/common/__init__.py

@@ -0,0 +1 @@
+"""Provide common files for the Matter Server."""

matter_server/common/helpers/json.py

@@ -13,8 +13,8 @@
 
 
 def json_encoder_default(obj: Any) -> Any:
-    """
-    Convert Special objects.
+    """Convert Special objects.
+
     Hand other objects to the original method.
     """
     if getattr(obj, "do_not_serialize", None):

matter_server/common/models/__init__.py

@@ -0,0 +1 @@
+"""Provide common models for the Matter Server."""

matter_server/common/models/device_type_instance.py

@@ -31,6 +31,7 @@ def __init__(
         endpoint: int,
         device_revision: int,
     ) -> None:
+        """Initialize the device type instance."""
         self.node = node
         self.device_type = device_type
         self.device_revision = device_revision
@@ -62,5 +63,6 @@ def get_cluster(self, cluster: type[_CLUSTER_T]) -> Optional[_CLUSTER_T]:
         return self.node.get_cluster(self.endpoint, cluster)
 
     def __repr__(self):
+        """Return the representation."""
         # pylint: disable=line-too-long
         return f"<MatterDeviceTypeInstance {self.device_type.__name__} (N:{self.node.node_id}, E:{self.endpoint})>"

matter_server/common/models/message.py

@@ -27,7 +27,7 @@ class ResultMessageBase:
 
 @dataclass
 class SuccessResultMessage(ResultMessageBase):
-    """Message sent when a Command has been succesfully executed."""
+    """Message sent when a Command has been successfully executed."""
 
     result: Any
 
@@ -43,7 +43,7 @@ class ErrorCode(IntEnum):
 
 @dataclass
 class ErrorResultMessage(ResultMessageBase):
-    """Message sent when a command did not execute succesfully"""
+    """Message sent when a command did not execute successfully."""
 
     error_code: ErrorCode
     details: Optional[str] = None

matter_server/common/models/node.py

@@ -214,4 +214,5 @@ def unique_id(self) -> str:
         )
 
     def __repr__(self):
+        """Return the representation."""
         return f"<MatterNode {self.node_id}>"

matter_server/common/models/node_device.py

@@ -35,18 +35,23 @@ class MatterNodeDevice(AbstractMatterNodeDevice):
     """Device that is the whole node."""
 
     def __init__(self, node: MatterNode) -> None:
+        """Initialize the node device."""
         self._node = node
 
     def node(self) -> MatterNode:
+        """Return the node of this device."""
         return self._node
 
     def device_info(self) -> Clusters.Basic:
+        """Return device info."""
         return self._node.root_device_type_instance.get_cluster(Clusters.Basic)
 
     def device_type_instances(self) -> list[MatterDeviceTypeInstance]:
+        """Return device type instances."""
         return self._node.device_type_instances
 
     def __repr__(self) -> str:
+        """Return the representation."""
         return f"<MatterNodeDevice (N:{self._node.node_id})>"
 
 
@@ -57,17 +62,21 @@ def __init__(
         self,
         bridged_device_type_instance: MatterDeviceTypeInstance[Aggregator],
     ) -> None:
+        """Initialize the bridged node device."""
         self.bridged_device_type_instance = bridged_device_type_instance
 
     def node(self) -> MatterNode:
+        """Return the node of this device."""
         return self.bridged_device_type_instance.node
 
     def device_info(self) -> Clusters.BridgedDeviceBasic:
+        """Return device info."""
         return self.bridged_device_type_instance.get_cluster(
             Clusters.BridgedDeviceBasic
         )
 
     def device_type_instances(self) -> list[MatterDeviceTypeInstance]:
+        """Return device type instances."""
         endpoint = self.bridged_device_type_instance.endpoint
         return [
             inst
@@ -76,5 +85,6 @@ def device_type_instances(self) -> list[MatterDeviceTypeInstance]:
         ]
 
     def __repr__(self) -> str:
+        """Return the representation."""
         bridged = self.bridged_device_type_instance
         return f"<MatterBridgedNodeDevice (N:{bridged.node.node_id}, E:{bridged.endpoint})>"

matter_server/server/device_controller.py

@@ -44,6 +44,7 @@ def __init__(
         self,
         server: MatterServer,
     ):
+        """Initialize the device controller."""
         self.server = server
         # Instantiate the underlying ChipDeviceController instance on the Fabric
         self.chip_controller: ChipDeviceController = (
@@ -84,7 +85,7 @@ async def start(self) -> None:
         LOGGER.debug("CHIP Device Controller Initialized")
 
     async def stop(self) -> None:
-        """ "Handle logic on server stop."""
+        """Handle logic on server stop."""
         # unsubscribe all node subscriptions
         for sub in self._subscriptions.values():
             await self._call_sdk(sub.Shutdown)

pyproject.toml

@@ -34,7 +34,8 @@ server = [
 ]
 test = [
   "black==22.10.0",
-  "flake8==5.0.4",
+  "flake8==6.0.0",
+  "flake8-docstrings==1.6.0",
   "isort==5.10.1",
   "pylint==2.15.8",
   "pytest==7.2.0",

requirements-test.txt

@@ -1,5 +1,6 @@
 black==22.10.0
 flake8==6.0.0
+flake8-docstrings==1.6.0
 isort==5.10.1
 pylint==2.15.8
 pytest==7.2.0

scripts/dump_fixer.py

@@ -16,6 +16,7 @@
 
 
 def process_node(node):
+    """Process a node."""
     print(f"Node {node.node_id}")
     for endpoint_id, endpoint_data in node.raw_data["attributes"].items():
         for cluster_name, cluster_info in endpoint_data.items():
@@ -59,6 +60,7 @@ def process_node(node):
 
 
 def main():
+    """Run the script."""
     item_space_printer = PrintButFirst(2)
 
     for node in get_nodes():

scripts/example.py

@@ -66,6 +66,7 @@
     )
 
     async def run_matter():
+        """Run the Matter server and client."""
         # start Matter Server
         await server.start()
 
@@ -77,6 +78,7 @@ async def run_matter():
                 await client.start_listening()
 
     async def handle_stop(loop: asyncio.AbstractEventLoop):
+        """Handle server stop."""
         await server.stop()
 
     # run the server

scripts/generate_devices.py

@@ -1,3 +1,4 @@
+"""Generate device types from matter-devices.xml."""
 import pathlib
 
 import black
@@ -12,6 +13,7 @@
 
 
 def gen_cls_name(name: str):
+    """Generate a class name from a cluster name."""
     # Convert uppercase words to titlecase
     name = "".join(
         # Don't mess up wifi name
@@ -36,6 +38,7 @@ def gen_cls_name(name: str):
 
 
 def main():
+    """Generate device types from matter-devices.xml."""
     data = xmltodict.parse(DEVICE_XML.read_text())
     output = [
         '''