lint and docstrings

Author: alexrudd2

MANIFEST.in

@@ -0,0 +1 @@
+include LICENSE

clickplc/__init__.py

@@ -1,4 +1,3 @@
-#!/usr/bin/python3
 """
 A Python driver for Koyo ClickPLC ethernet units.
 

clickplc/driver.py

@@ -86,7 +86,8 @@ async def get(self, address: str = None) -> dict:
                                  'provided when driver initialized')
             results = {}
             for category, address in self.active_addresses.items():
-                results.update(await getattr(self, '_get_' + category)(address['min'], address['max']))
+                results.update(await getattr(self, '_get_' + category)
+                                            (address['min'], address['max']))
             return {tag_name: results[tag_info['id'].lower()]
                     for tag_name, tag_info in self.tags.items()}
 
@@ -498,13 +499,15 @@ def _load_tags(self, tag_filepath: str) -> dict:
 
     @staticmethod
     def _get_address_ranges(tags: dict) -> dict:
-        """Parse the loaded tags to determine the range of addresses that must be
-        queried to return all values"""
+        """Determine range of addresses required.
+
+        Parse the loaded tags to determine the range of addresses that must be
+        queried to return all values
+        """
         address_dict = defaultdict(lambda: {'min': 1, 'max': 1})
         for tag_info in tags.values():
             i = next(i for i, s in enumerate(tag_info['id']) if s.isdigit())
             category, index = tag_info['id'][:i].lower(), int(tag_info['id'][i:])
             address_dict[category]['min'] = min(address_dict[category]['min'], index)
             address_dict[category]['max'] = max(address_dict[category]['max'], index)
         return address_dict
-

clickplc/mock.py

@@ -1,3 +1,11 @@
+"""
+Python mock driver for AutomationDirect (formerly Koyo) ClickPLCs.
+
+Uses local storage instead of remote communications.
+
+Distributed under the GNU General Public License v2
+Copyright (C) 2021 NuMat Technologies
+"""
 from collections import defaultdict
 from unittest.mock import MagicMock
 
@@ -10,14 +18,16 @@
 
 
 class AsyncMock(MagicMock):
-    """Magic mock that works with async methods"""
+    """Magic mock that works with async methods."""
+
     async def __call__(self, *args, **kwargs):
+        """Convert regular mocks into into an async coroutine."""
         return super(AsyncMock, self).__call__(*args, **kwargs)
 
 
 class ClickPLC(realClickPLC):
-    """A version of the driver with the remote communication replaced with local data storage
-    for testing"""
+    """A version of the driver replacing remote communication with local storage for testing."""
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.client = AsyncMock()

clickplc/tests/test_driver.py

@@ -1,4 +1,4 @@
-import asyncio
+"""Test the driver correctly parses a tags file and responds with correct data."""
 
 import pytest
 
@@ -7,15 +7,19 @@
 
 @pytest.fixture
 def plc_driver():
+    """Confirm the driver correctly initializes without a tags file."""
     return ClickPLC('fake ip')
 
 
 @pytest.fixture
 def tagged_driver():
+    """Confirm the driver correctly initializes with a good tags file."""
     return ClickPLC('fake ip', 'tests/plc_tags.csv')
 
+
 @pytest.fixture
 def expected_tags():
+    """Return the tags defined in the tags file."""
     return {
         'IO2_24V_OK': {'address': {'start': 16397}, 'id': 'C13', 'type': 'bool'},
         'IO2_Module_OK': {'address': {'start': 16396}, 'id': 'C12', 'type': 'bool'},
@@ -38,16 +42,19 @@ def expected_tags():
 
 
 def test_get_tags(tagged_driver, expected_tags):
+    """Confirm that the driver returns correct values on get() calls."""
     assert expected_tags == tagged_driver.get_tags()
 
 
 def test_unsupported_tags():
+    """Confirm the driver detects an improper tags file."""
     with pytest.raises(TypeError, match='unsupported data type'):
         ClickPLC('fake ip', 'tests/bad_tags.csv')
 
 
 @pytest.mark.asyncio
 async def test_tagged_driver(tagged_driver, expected_tags):
+    """Test a roundtrip with the driver using a tags file."""
     await tagged_driver.set('VAH_101_OK', True)
     state = await tagged_driver.get()
     assert state.get('VAH_101_OK')
@@ -57,6 +64,7 @@ async def test_tagged_driver(tagged_driver, expected_tags):
 @pytest.mark.asyncio
 @pytest.mark.parametrize('prefix', ['x', 'y'])
 async def test_bool_roundtrip(plc_driver, prefix):
+    """Confirm x and y bools are read back correctly after being set."""
     await plc_driver.set(f'{prefix}2', True)
     await plc_driver.set(f'{prefix}3', [False, True])
     expected = {f'{prefix}001': False, f'{prefix}002': True, f'{prefix}003': False,
@@ -66,6 +74,7 @@ async def test_bool_roundtrip(plc_driver, prefix):
 
 @pytest.mark.asyncio
 async def test_c_roundtrip(plc_driver):
+    """Confirm c bools are read back correctly after being set."""
     await plc_driver.set('c2', True)
     await plc_driver.set('c3', [False, True])
     expected = {'c1': False, 'c2': True, 'c3': False, 'c4': True, 'c5': False}
@@ -74,6 +83,7 @@ async def test_c_roundtrip(plc_driver):
 
 @pytest.mark.asyncio
 async def test_df_roundtrip(plc_driver):
+    """Confirm df floats are read back correctly after being set."""
     await plc_driver.set('df2', 2.0)
     await plc_driver.set('df3', [3.0, 4.0])
     expected = {'df1': 0.0, 'df2': 2.0, 'df3': 3.0, 'df4': 4.0, 'df5': 0.0}
@@ -82,6 +92,7 @@ async def test_df_roundtrip(plc_driver):
 
 @pytest.mark.asyncio
 async def test_ds_roundtrip(plc_driver):
+    """Confirm ds ints are read back correctly after being set."""
     await plc_driver.set('ds2', 2)
     await plc_driver.set('ds3', [3, 4])
     expected = {'ds1': 0, 'ds2': 2, 'ds3': 3, 'ds4': 4, 'ds5': 0}
@@ -90,6 +101,7 @@ async def test_ds_roundtrip(plc_driver):
 
 @pytest.mark.asyncio
 async def test_get_error_handling(plc_driver):
+    """Confirm the driver gives an error on invalid get() calls."""
     with pytest.raises(ValueError, match='An address must be supplied'):
         await plc_driver.get()
     with pytest.raises(ValueError, match='End address must be greater than start address'):
@@ -102,68 +114,74 @@ async def test_get_error_handling(plc_driver):
 
 @pytest.mark.asyncio
 async def test_set_error_handling(plc_driver):
+    """Confirm the driver gives an error on invalid set() calls."""
     with pytest.raises(ValueError, match='foo currently unsupported'):
         await plc_driver.set('foo1', 1)
 
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize('prefix', ['x', 'y'])
 async def test_xy_error_handling(plc_driver, prefix):
-    with pytest.raises(ValueError, match='address must be \*01-\*16.'):
+    """Ensure errors are handled for invalid requests of x and y registers."""
+    with pytest.raises(ValueError, match=r'address must be \*01-\*16.'):
         await plc_driver.get(f'{prefix}17')
-    with pytest.raises(ValueError, match='address must be in \[001, 816\].'):
+    with pytest.raises(ValueError, match=r'address must be in \[001, 816\].'):
         await plc_driver.get(f'{prefix}1001')
-    with pytest.raises(ValueError, match='address must be \*01-\*16.'):
+    with pytest.raises(ValueError, match=r'address must be \*01-\*16.'):
         await plc_driver.get(f'{prefix}1-{prefix}17')
-    with pytest.raises(ValueError, match='address must be in \[001, 816\].'):
+    with pytest.raises(ValueError, match=r'address must be in \[001, 816\].'):
         await plc_driver.get(f'{prefix}1-{prefix}1001')
-    with pytest.raises(ValueError, match='address must be \*01-\*16.'):
+    with pytest.raises(ValueError, match=r'address must be \*01-\*16.'):
         await plc_driver.set(f'{prefix}17', True)
-    with pytest.raises(ValueError, match='address must be in \[001, 816\].'):
+    with pytest.raises(ValueError, match=r'address must be in \[001, 816\].'):
         await plc_driver.set(f'{prefix}1001', True)
-    with pytest.raises(ValueError, match='Data list longer than available addresses.'):
+    with pytest.raises(ValueError, match=r'Data list longer than available addresses.'):
         await plc_driver.set(f'{prefix}816', [True, True])
 
 
 @pytest.mark.asyncio
 async def test_c_error_handling(plc_driver):
-    with pytest.raises(ValueError, match='C start address must be 1-2000.'):
+    """Ensure errors are handled for invalid requests of c registers."""
+    with pytest.raises(ValueError, match=r'C start address must be 1-2000.'):
         await plc_driver.get('c2001')
-    with pytest.raises(ValueError, match='C end address must be >start and <2000.'):
+    with pytest.raises(ValueError, match=r'C end address must be >start and <2000.'):
         await plc_driver.get('c1-c2001')
-    with pytest.raises(ValueError, match='C start address must be 1-2000.'):
+    with pytest.raises(ValueError, match=r'C start address must be 1-2000.'):
         await plc_driver.set('c2001', True)
-    with pytest.raises(ValueError, match='Data list longer than available addresses.'):
+    with pytest.raises(ValueError, match=r'Data list longer than available addresses.'):
         await plc_driver.set('c2000', [True, True])
 
 
 @pytest.mark.asyncio
 async def test_df_error_handling(plc_driver):
-    with pytest.raises(ValueError, match='DF must be in \[1, 500\]'):
+    """Ensure errors are handled for invalid requests of df registers."""
+    with pytest.raises(ValueError, match=r'DF must be in \[1, 500\]'):
         await plc_driver.get('df501')
-    with pytest.raises(ValueError, match='DF end must be in \[1, 500\]'):
+    with pytest.raises(ValueError, match=r'DF end must be in \[1, 500\]'):
         await plc_driver.get('df1-df501')
-    with pytest.raises(ValueError, match='DF must be in \[1, 500\]'):
+    with pytest.raises(ValueError, match=r'DF must be in \[1, 500\]'):
         await plc_driver.set('df501', 1.0)
-    with pytest.raises(ValueError, match='Data list longer than available addresses.'):
+    with pytest.raises(ValueError, match=r'Data list longer than available addresses.'):
         await plc_driver.set('df500', [1.0, 2.0])
 
 
 @pytest.mark.asyncio
 async def test_ds_error_handling(plc_driver):
-    with pytest.raises(ValueError, match='DS must be in \[1, 4500\]'):
+    """Ensure errors are handled for invalid requests of ds registers."""
+    with pytest.raises(ValueError, match=r'DS must be in \[1, 4500\]'):
         await plc_driver.get('ds4501')
-    with pytest.raises(ValueError, match='DS end must be in \[1, 4500\]'):
+    with pytest.raises(ValueError, match=r'DS end must be in \[1, 4500\]'):
         await plc_driver.get('ds1-ds4501')
-    with pytest.raises(ValueError, match='DS must be in \[1, 4500\]'):
+    with pytest.raises(ValueError, match=r'DS must be in \[1, 4500\]'):
         await plc_driver.set('ds4501', 1)
-    with pytest.raises(ValueError, match='Data list longer than available addresses.'):
+    with pytest.raises(ValueError, match=r'Data list longer than available addresses.'):
         await plc_driver.set('ds4500', [1, 2])
 
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize('prefix', ['x', 'y', 'c'])
 async def test_bool_typechecking(plc_driver, prefix):
+    """Ensure errors are handled for set() requests that should be bools."""
     with pytest.raises(ValueError, match='Expected .+ as a bool'):
         await plc_driver.set(f'{prefix}1', 1)
     with pytest.raises(ValueError, match='Expected .+ as a bool'):
@@ -172,6 +190,7 @@ async def test_bool_typechecking(plc_driver, prefix):
 
 @pytest.mark.asyncio
 async def test_df_typechecking(plc_driver):
+    """Ensure errors are handled for set() requests that should be floats."""
     await plc_driver.set('df1', 1)
     with pytest.raises(ValueError, match='Expected .+ as a float'):
         await plc_driver.set('df1', True)
@@ -181,6 +200,7 @@ async def test_df_typechecking(plc_driver):
 
 @pytest.mark.asyncio
 async def test_ds_typechecking(plc_driver):
+    """Ensure errors are handled for set() requests that should be ints."""
     with pytest.raises(ValueError, match='Expected .+ as a int'):
         await plc_driver.set('ds1', 1.0)
     with pytest.raises(ValueError, match='Expected .+ as a int'):

setup.cfg

@@ -3,4 +3,9 @@ universal = 1
 
 [flake8]
 max-complexity = 15
-max-line-length = 89
+max-line-length = 99
+docstring-convention = pep257
+
+# no docstrings in __init__.py
+# line breaks should be before binary operators
+ignore = D104,D107,W503