fix: add darglint (#66)

girasolenergy/SWTeam#18

---------

Co-authored-by: senri <[email protected]>

Author: OkamotoSenri

openems/__main__.py

@@ -12,7 +12,14 @@
 @click.option('--username', default='admin')
 @click.option('--password', default='password')
 def openems_cli(ctx, server_url, username, password):
-    """OpenEMS CLI."""  # noqa: D403
+    """Command-line interface for OpenEMS.
+
+    Args:
+        ctx: Click context object.
+        server_url: OpenEMS server WebSocket URL.
+        username: Username for authentication.
+        password: Password for authentication.
+    """
     client = api.OpenEMSAPIClient(server_url, username, password)
     ctx.obj = {
         'client': client,
@@ -22,7 +29,11 @@ def openems_cli(ctx, server_url, username, password):
 @openems_cli.command()
 @click.pass_context
 def get_edge_list(ctx):
-    """Get OpenEMS Edge List."""
+    """Get OpenEMS Edge List.
+
+    Args:
+        ctx: Click context object.
+    """
     edges = ctx.obj['client'].get_edges()
 
     for edge in edges:
@@ -33,7 +44,12 @@ def get_edge_list(ctx):
 @click.pass_context
 @click.argument('edge-id')
 def get_edge_config(ctx, edge_id):
-    """Get OpenEMS Edge Config."""
+    """Get OpenEMS Edge Config.
+
+    Args:
+        ctx: Click context object.
+        edge_id: Edge device ID.
+    """
     edge_config = ctx.obj['client'].get_edge_config(edge_id)
 
     click.echo(click.style(json.dumps(edge_config, indent=2), fg='green'))
@@ -43,7 +59,12 @@ def get_edge_config(ctx, edge_id):
 @click.pass_context
 @click.argument('edge-id')
 def get_meter_list(ctx, edge_id):
-    """Get OpenEMS Meter List."""
+    """Get OpenEMS Meter List.
+
+    Args:
+        ctx: Click context object.
+        edge_id: Edge device ID.
+    """
     meters = ctx.obj['client'].get_meter_list(edge_id)
 
     for (k, _) in meters.items():
@@ -54,7 +75,12 @@ def get_meter_list(ctx, edge_id):
 @click.pass_context
 @click.argument('edge-id')
 def get_pvinverter_list(ctx, edge_id):
-    """Get OpenEMS PVInverter List."""
+    """Get OpenEMS PVInverter List.
+
+    Args:
+        ctx: Click context object.
+        edge_id: Edge device ID.
+    """
     pvinverters = ctx.obj['client'].get_pvinverter_list(edge_id)
 
     for (k, _) in pvinverters.items():
@@ -66,7 +92,13 @@ def get_pvinverter_list(ctx, edge_id):
 @click.argument('edge-id')
 @click.argument('component-id')
 def get_channel_list(ctx, edge_id, component_id):
-    """Get OpenEMS Channel List."""
+    """Get OpenEMS Channel List.
+
+    Args:
+        ctx: Click context object.
+        edge_id: Edge device ID.
+        component_id: Component ID (e.g., meter ID, inverter ID).
+    """
     channels = ctx.obj['client'].get_channels_of_component(edge_id, component_id)['channels']
     for channel in channels:
         click.echo(click.style(f'{component_id}/{channel["id"]}', fg='green'))
@@ -79,7 +111,15 @@ def get_channel_list(ctx, edge_id, component_id):
 @click.argument('name')
 @click.argument('value')
 def update_component_config(ctx, edge_id, component_id, name, value):
-    """Update OpenEMS Component Config."""
+    """Update OpenEMS Component Config.
+
+    Args:
+        ctx: Click context object.
+        edge_id: Edge device ID.
+        component_id: Component ID to update.
+        name: Configuration parameter name.
+        value: New value for the configuration parameter.
+    """
     r = ctx.obj['client'].update_component_config_from_name_value(edge_id, component_id, name, value)
     click.echo(click.style(f'{r}', fg='green'))
 
@@ -92,7 +132,16 @@ def update_component_config(ctx, edge_id, component_id, name, value):
 @click.argument('end', type=click.DateTime(['%Y-%m-%d']))
 @click.argument('resolution-sec', type=int)
 def get_channel_data(ctx, edge_id, channel, start, end, resolution_sec):
-    """Get OpenEMS Channel Data."""
+    """Get OpenEMS Channel Data.
+
+    Args:
+        ctx: Click context object.
+        edge_id: Edge device ID.
+        channel: Channel name (e.g., 'meter0/ActivePower').
+        start: Start date for data query.
+        end: End date for data query.
+        resolution_sec: Data resolution in seconds.
+    """
     df = ctx.obj['client'].query_historic_timeseries_data(edge_id, start.date(), end.date(), [channel], resolution_sec)
 
     click.echo(click.style(df.to_csv(), fg='green'))

openems/api.py

@@ -15,7 +15,13 @@ class OpenEMSAPIClient():
     """OpenEMS API Client Class."""
 
     def __init__(self, server_url, username, password):
-        """Create client instance and initialize connection helpers."""
+        """Create client instance and initialize connection helpers.
+
+        Args:
+            server_url: OpenEMS server WebSocket URL.
+            username: Username for authentication.
+            password: Password for authentication.
+        """
         self.server_url = server_url
         self.username = username
         self.password = password
@@ -27,7 +33,15 @@ def __del__(self):
         self._bridge.shutdown()
 
     async def login(self):
-        """Return an authenticated websocket server connection."""
+        """Return an authenticated websocket server connection.
+
+        Returns:
+            Server: Authenticated WebSocket server connection.
+
+        Raises:
+            APIError: If authentication fails.
+            jsonrpc_base.jsonrpc.ProtocolError: If an unexpected protocol error occurs.
+        """
         if self._server is None or not hasattr(self._server, 'connected') or not self._server.connected:
             server = Server(self.server_url)
             await server.ws_connect()
@@ -41,7 +55,11 @@ async def login(self):
         return self._server
 
     def get_edges(self):
-        """Call getEdges API."""
+        """Call getEdges API.
+
+        Returns:
+            list: List of edge devices with their configuration.
+        """
         async def f():
             server = await self.login()
             page = 0
@@ -62,7 +80,14 @@ async def f():
         return self._bridge.run(f)
 
     def get_edge_config(self, edge_id):
-        """Call getEdgeConfig API."""
+        """Call getEdgeConfig API.
+
+        Args:
+            edge_id: Edge device ID.
+
+        Returns:
+            dict: Edge configuration including components and their settings.
+        """
         async def f():
             server = await self.login()
             try:
@@ -82,7 +107,15 @@ async def f():
         return self._bridge.run(f)
 
     def get_channels_of_component(self, edge_id, component_id):
-        """Call getChannelsOfComponent API."""
+        """Call getChannelsOfComponent API.
+
+        Args:
+            edge_id: Edge device ID.
+            component_id: Component ID to query channels for.
+
+        Returns:
+            dict: Component channels information including channel IDs and metadata.
+        """
         async def f():
             server = await self.login()
             try:
@@ -111,7 +144,18 @@ async def f():
         return self._bridge.run(f)
 
     def query_historic_timeseries_data(self, edge_id, start, end, channels, resolution_sec=None):
-        """Call edgeRpc.queryHistoricTimeseriesData API."""
+        """Call edgeRpc.queryHistoricTimeseriesData API.
+
+        Args:
+            edge_id: Edge device ID.
+            start: Start date for data query.
+            end: End date for data query.
+            channels: List of channel names to query (e.g., ['meter0/ActivePower']).
+            resolution_sec: Optional data resolution in seconds.
+
+        Returns:
+            pd.DataFrame: Time-series data with timestamps as index and channels as columns.
+        """
         async def f():
             server = await self.login()
             params = {
@@ -144,7 +188,16 @@ async def f():
         return self._bridge.run(f)
 
     def update_component_config(self, edge_id, component_id, properties):
-        """Call edgeRpc.updateComponentConfig API."""
+        """Call edgeRpc.updateComponentConfig API.
+
+        Args:
+            edge_id: Edge device ID.
+            component_id: Component ID to update.
+            properties: List of property dictionaries with 'name' and 'value' keys.
+
+        Returns:
+            dict: Update result from the API.
+        """
         async def f():
             server = await self.login()
             try:
@@ -169,6 +222,15 @@ def update_component_config_from_name_value(self, edge_id, component_id, name, v
         """Call edgeRpc.updateComponentConfig API.
 
         This function has name and value argument instead of properties argument of update_component_config method.
+
+        Args:
+            edge_id: Edge device ID.
+            component_id: Component ID to update.
+            name: Configuration parameter name.
+            value: New value for the configuration parameter.
+
+        Returns:
+            dict: Update result from the API.
         """
         return self.update_component_config(
             edge_id,
@@ -179,13 +241,27 @@ def update_component_config_from_name_value(self, edge_id, component_id, name, v
         )
 
     def get_meter_list(self, edge_id):
-        """Extract meter list from edge config."""
+        """Extract meter list from edge config.
+
+        Args:
+            edge_id: Edge device ID.
+
+        Returns:
+            dict: Dictionary of meter components keyed by component ID.
+        """
         edge_config = self.get_edge_config(edge_id)
         components = edge_config['components']
         return dict([(k, v) for (k, v) in components.items() if v['factoryId'].split('.')[0] == 'Meter'])
 
     def get_pvinverter_list(self, edge_id):
-        """Extract pvinverter list from edge config."""
+        """Extract pvinverter list from edge config.
+
+        Args:
+            edge_id: Edge device ID.
+
+        Returns:
+            dict: Dictionary of PV inverter components keyed by component ID.
+        """
         edge_config = self.get_edge_config(edge_id)
         components = edge_config['components']
         return dict([(k, v) for (k, v) in components.items() if v['factoryId'].split('.')[0] == 'PVInverter'])

openems/exceptions.py

@@ -2,9 +2,14 @@
 
 
 class APIError(Exception):
-    """HTTPError Exception Class."""
+    """OpenEMS API error with error code."""
 
     def __init__(self, message: str, code: int):
-        """__init__."""
+        """Initialize APIError.
+
+        Args:
+            message: Error message describing the error.
+            code: Numeric error code from the API.
+        """
         super().__init__(message)
         self.code = code

tox.ini

@@ -29,6 +29,7 @@ deps =
   pep8-naming
   hacking==7.0.0
   flake8-bugbear
+  darglint
 
 commands = flake8