Draft: Use pydocstyle (#2)

* Install pytest-pydocstyle * Configure pytest to use pydocstyle * Lock with DLS PyPi * Ignore module & package docstrings * Fix loading docstrings * Fix configurable docstrings * Fix topic_naming docstrings * Fix singleton docstrings * Fix byte_format docstrings * Fix source docstrings * Fix sink docstrings * Fix state_interface docstrings * Bump pydocstyle to 6.1.1 * Fix kafka docstrings * Fix internal docstrings * Fix slave docstrings * Fix master docstrings * Fix base docstrings * Fix ticker docstrings * Fix device_simulation docstrings * Fix system_simulation docstrings * Fix component docstrings * Fix typedefs docstrings * Fix lifetime_runnable docstrings * Fix device docstrings * Fix adapter docstrings * Fix tcp docstrings * Fix regex_command docstrings * Fix command_interpreter docstrings * Fix composed docstrings * Fix remote_controlled docstrings * Fix shutter docstrings * Fix trampoline docstrings * Fix _version_git docstrings * Re-lock pipfile.lock * Add cli docstrings * Add D418 to pydocstyle ignore * Fix event_router docstrings * Refactor epicsadapter * Update EpicsAdapter adapters * Update example configs * Fix base docstrings * Fix shutter docstrings * Fix cryostream docstrings * Fix states docstrings * Fix status docstrings * Enable pydocstyle linting * Add simple docstrings to pneumatic * Make flake8 complient * Added docstrings to femto.py; Changed 'records' function in femto, pneumatic and epicsadapter to 'on_db_load' to better reflect what it does; Updated Pipfile to include charset-normalizer * Fixed some docstring formatting * Fixed line lengths * Update tickit/devices/pneumatic/pneumatic.py Co-authored-by: Garry O'Donnell <[email protected]> * Removed whitespace * Changed a couple of docstrings to include args and return values * Remove charset-normalizer * Edited set_state function * Fix typechecking error Co-authored-by: Angus Collett <[email protected]> Co-authored-by: Ollie Copping <[email protected]>
DiamondLightSource · Sep 23, 2021 · 1cf7099 · 1cf7099
1 parent 3173744
commit 1cf7099
Show file tree

Hide file tree

Showing 44 changed files with 1,293 additions and 891 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -3,6 +3,7 @@
     "python.linting.pylintEnabled": false,
     "python.linting.flake8Enabled": true,
     "python.linting.mypyEnabled": true,
+    "python.linting.pydocstyleEnabled": true,
     "python.linting.enabled": true,
     "python.testing.pytestArgs": [],
     "python.testing.unittestEnabled": false,

diff --git a/Pipfile b/Pipfile
@@ -6,13 +6,11 @@ verify_ssl = true
 [dev-packages]
 # Pinning black stops us having to allow pre-releases globally
 black = "==21.7b0"
-
 # Pins to make lockfile usable on multiple Python versions and platforms
 mypy = "*"
 typed-ast = "*"
 atomicwrites = "*"
 importlib-metadata = "*"
-
 # Test and docs dependencies
 pytest-cov = "*"
 pytest-mypy = "*"
@@ -25,6 +23,7 @@ mock = "*"
 types-mock = "*"
 types-PyYAML = "*"
 pytest-asyncio = "*"
+pytest-pydocstyle = "*"
 
 [packages]
 # Required by immutables

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/examples/configs/attns.yaml b/examples/configs/attns.yaml
@@ -1,10 +1,10 @@
 - tickit.core.components.device_simulation.DeviceSimulation:
     adapters: 
      - tickit.devices.pneumatic.pneumatic.PneumaticAdapter: 
-        db_file: tickit/devices/pneumatic/db_files/filter1.db 
+        ioc_name: PNEUMATIC
+        db_file: tickit/devices/pneumatic/db_files/filter1.db
     device:
       tickit.devices.pneumatic.pneumatic.Pneumatic:
-        name: "PNEUMATIC"
         initial_speed: 2.5
         initial_state: False
     inputs: {}

diff --git a/examples/configs/current-monitor.yaml b/examples/configs/current-monitor.yaml
@@ -1,10 +1,10 @@
 - tickit.core.components.device_simulation.DeviceSimulation:
     adapters: 
      - tickit.devices.femto.femto.FemtoAdapter: 
-        db_file: tickit/devices/femto/record.db 
+        ioc_name: FEMTO
+        db_file: tickit/devices/femto/record.db
     device:
       tickit.devices.femto.femto.Femto:
-        name: "FEMTO"
         initial_gain: 2.5
         initial_current: 0.0
     inputs:

diff --git a/examples/devices/remote_controlled.py b/examples/devices/remote_controlled.py
@@ -14,7 +14,7 @@
 
 
 class RemoteControlled(ConfigurableDevice):
-    """A trivial toy device which is controlled by an adapter"""
+    """A trivial toy device which is controlled by an adapter."""
 
     #: An empty typed mapping of device inputs
     Inputs: TypedDict = TypedDict("Inputs", {})
@@ -27,7 +27,7 @@ def __init__(
         initial_unobserved: float = 42,
         initial_hidden: float = 3.14,
     ) -> None:
-        """A constructor of the sink, which configures some initial values
+        """A RemoteControlled constructor of the, which configures various initial values.
 
         Args:
             initial_observed (float): The initial value of the observed device property.
@@ -42,23 +42,22 @@ def __init__(
         self.hidden = initial_hidden
 
     def update(self, time: SimTime, inputs: Inputs) -> DeviceUpdate[Outputs]:
-        """The update method which produces an output mapping containing the observed value
+        """The update method which produces an output mapping containing the observed value.
 
         Args:
-            time (SimTime): The current simulation time (in nanoseconds)
-            inputs (State): A mapping of inputs to the device and their values
+            time (SimTime): The current simulation time (in nanoseconds).
+            inputs (State): A mapping of inputs to the device and their values.
 
         Returns:
             DeviceUpdate[Outputs]:
                 The produced update event which contains the observed value, the device
-                never requests a callback
+                never requests a callback.
         """
-
         return DeviceUpdate(RemoteControlled.Outputs(observed=self.observed), None)
 
 
 class RemoteControlledAdapter(ComposedAdapter, ConfigurableAdapter):
-    """A trivial composed adapter which gets and sets device properties"""
+    """A trivial composed adapter which gets and sets device properties."""
 
     _device: RemoteControlled
 
@@ -68,14 +67,14 @@ def __init__(
         raise_interrupt: Callable[[], Awaitable[None]],
         server: ServerConfig,
     ) -> None:
-        """A constructor of the Shutter adapter, which builds the TcpServer
+        """A constructor of the Shutter adapter, which builds the configured server.
 
         Args:
-            device (Device): The device which this adapter is attached to
+            device (Device): The device which this adapter is attached to.
             raise_interrupt (Callable): A callback to request that the device is
-                updated immediately
+                updated immediately.
             server (ServerConfig): The immutable data container used to configure a
-                server
+                server.
         """
         super().__init__(
             device,
@@ -85,138 +84,138 @@ def __init__(
         )
 
     async def on_connect(self) -> AsyncIterable[bytes]:
-        """An on_connect method which continiously sends the unobserved value to the client
+        """An on_connect method which continiously sends the unobserved value to the client.
 
         Returns:
             AsyncIterable[bytes]:
-                An asynchronous iterable which regularly outputs the unobserved value
+                An asynchronous iterable which regularly outputs the unobserved value.
         """
         while True:
             await asyncio.sleep(5.0)
             yield "U is {}".format(self._device.unobserved).encode("utf-8")
 
     @RegexCommand(b"\x01")
     async def get_observed_bytes(self) -> bytes:
-        """A regex bytes command which returns the byte encoded value of observed
+        """A regex bytes command which returns the byte encoded value of observed.
 
         Returns:
-            bytes: The big endian float encoded value of observed
+            bytes: The big endian float encoded value of observed.
         """
         return struct.pack(">f", self._device.observed)
 
     @RegexCommand(r"O", format="utf-8")
     async def get_observed_str(self) -> bytes:
-        """A regex string command which returns the utf-8 encoded value of observed
+        """A regex string command which returns the utf-8 encoded value of observed.
 
         Returns:
-            bytes: The utf-8 encoded value of observed
+            bytes: The utf-8 encoded value of observed.
         """
         return str(self._device.observed).encode("utf-8")
 
     @RegexCommand(b"\x01(.{4})", interrupt=True)
     async def set_observed_bytes(self, value: bytes) -> bytes:
-        """A regex bytes command which sets and echos the value of observed
+        """A regex bytes command which sets and echos the value of observed.
 
         Args:
-            value (bytes): The new big endian float encoded value of observed
+            value (bytes): The new big endian float encoded value of observed.
 
         Returns:
-            bytes: The big endian float encoded value of observed
+            bytes: The big endian float encoded value of observed.
         """
         self._device.observed = struct.unpack(">f", value)[0]
         return struct.pack(">f", self._device.observed)
 
     @RegexCommand(r"O=(\d+\.?\d*)", interrupt=True, format="utf-8")
     async def set_observed_str(self, value: float) -> bytes:
-        """A regex string command which sets and echos the value of observed
+        """A regex string command which sets and echos the value of observed.
 
         Args:
-            value (int): The new value of observed
+            value (int): The new value of observed.
 
         Returns:
-            bytes: The utf-8 encoded value of observed
+            bytes: The utf-8 encoded value of observed.
         """
         self._device.observed = value
         return "Observed set to {}".format(self._device.observed).encode("utf-8")
 
     @RegexCommand(b"\x02")
     async def get_unobserved_bytes(self) -> bytes:
-        """A regex bytes command which returns the byte encoded value of unobserved
+        """A regex bytes command which returns the byte encoded value of unobserved.
 
         Returns:
-            bytes: The big endian float encoded value of unobserved
+            bytes: The big endian float encoded value of unobserved.
         """
         return struct.pack(">f", self._device.unobserved)
 
     @RegexCommand(r"U", format="utf-8")
     async def get_unobserved_str(self) -> bytes:
-        """A regex string command which returns the utf-8 encoded value of unobserved
+        """A regex string command which returns the utf-8 encoded value of unobserved.
 
         Returns:
-            bytes: The utf-8 encoded value of unobserved
+            bytes: The utf-8 encoded value of unobserved.
         """
         return str(self._device.unobserved).encode("utf-8")
 
     @RegexCommand(b"\x02(.{4})")
     async def set_unobserved_bytes(self, value: bytes) -> bytes:
-        """A regex bytes command which sets and echos the value of unobserved
+        """A regex bytes command which sets and echos the value of unobserved.
 
         Args:
-            value (bytes): The new big endian float encoded value of unobserved
+            value (bytes): The new big endian float encoded value of unobserved.
 
         Returns:
-            bytes: The big endian float encoded value of unobserved
+            bytes: The big endian float encoded value of unobserved.
         """
         self._device.unobserved = struct.unpack(">f", value)[0]
         return struct.pack(">f", self._device.unobserved)
 
     @RegexCommand(r"U=(\d+\.?\d*)", format="utf-8")
     async def set_unobserved_str(self, value: float) -> bytes:
-        """A regex string command which sets and echos the value of unobserved
+        """A regex string command which sets and echos the value of unobserved.
 
         Args:
-            value (int): The new value of unobserved
+            value (int): The new value of unobserved.
 
         Returns:
-            bytes: The utf-8 encoded value of unobserved
+            bytes: The utf-8 encoded value of unobserved.
         """
         self._device.unobserved = value
         return "Unobserved set to {}".format(self._device.unobserved).encode("utf-8")
 
     @RegexCommand(chr(0x1F95A), format="utf-8")
     async def misc(self) -> bytes:
-        """A regex string command which returns a utf-8 encoded character
+        """A regex string command which returns a utf-8 encoded character.
 
         Returns:
-            bytes: A utf-8 encoded character
+            bytes: A utf-8 encoded character.
         """
         return chr(0x1F430).encode("utf-8")
 
     @RegexCommand(r"H=(\d+\.?\d*)", format="utf-8")
     async def set_hidden(self, value: float) -> None:
-        """A regex string command which sets the value of hidden
+        """A regex string command which sets the value of hidden.
 
         Args:
-            value (float): The new value of hidden
+            value (float): The new value of hidden.
         """
         LOGGER.info("Hidden set to {}".format(self._device.hidden))
 
     @RegexCommand(r"H", format="utf-8")
     async def get_hidden(self) -> None:
-        """A regex string command which returns nothing, hidden cannot be shown"""
+        """A regex string command which returns nothing, hidden cannot be shown."""
         pass
 
     @RegexCommand(r"O\?(\d+)", format="utf-8")
     async def yield_observed(self, n: int = 10) -> AsyncIterable[bytes]:
-        """A regex string command which sends observed numerous times
+        """A regex string command which sends observed numerous times.
 
         Args:
             n (int): The number of times which observed should be sent. Defaults to 10.
 
         Returns:
             AsyncIterable[bytes]:
                 An asynchronous iterable which yields the value of observed the
-                specified number of times with a fixed delay
+                specified number of times with a fixed delay.
         """
         for i in range(1, int(n)):
             await asyncio.sleep(1.0)

diff --git a/examples/devices/shutter.py b/examples/devices/shutter.py
@@ -13,7 +13,7 @@
 
 
 class Shutter(ConfigurableDevice):
-    """A toy device which downscales flux according to a set position
+    """A toy device which downscales flux according to a set position.
 
     A toy device which produces an output flux which is downscaled from the input flux
     according to an internal state position. The position may be altered by setting new
@@ -29,7 +29,7 @@ class Shutter(ConfigurableDevice):
     def __init__(
         self, default_position: float, initial_position: Optional[float] = None
     ) -> None:
-        """A constructor of the Shutter which configures the initial and default position
+        """A Shutter constructor which configures the initial and default position.
 
         Args:
             default_position (float): The initial target position of the shutter
@@ -44,7 +44,7 @@ def __init__(
 
     @staticmethod
     def move(position: float, target: float, rate: float, period: SimTime) -> float:
-        """A helper method used to compute the new position of a shutter
+        """A helper method used to compute the new position of a shutter.
 
         A helper method used to compute the new position of a shutter given a target
         position, a rate of change and a period over which the change occurs. Movement
@@ -67,15 +67,15 @@ def move(position: float, target: float, rate: float, period: SimTime) -> float:
         return position
 
     def update(self, time: SimTime, inputs: Inputs) -> DeviceUpdate[Outputs]:
-        """The update method which moves the shutter and produces a downscaled flux
+        """The update method which moves the shutter and produces a downscaled flux.
 
         The update method which adjusts the position according to the target position,
         computes the transmitted flux and produces the output flux with a request to be
-        called back in 100ms if the if the shutter continues to move
+        called back in 100ms if the if the shutter continues to move.
 
         Args:
-            time (SimTime): The current simulation time (in nanoseconds)
-            inputs (State): A mapping of inputs to the device and their values
+            time (SimTime): The current simulation time (in nanoseconds).
+            inputs (State): A mapping of inputs to the device and their values.
 
         Returns:
             DeviceUpdate[Outputs]:
@@ -99,7 +99,7 @@ def update(self, time: SimTime, inputs: Inputs) -> DeviceUpdate[Outputs]:
 
 
 class ShutterAdapter(ComposedAdapter, ConfigurableAdapter):
-    """A toy composed adapter which gets shutter position and target and sets target"""
+    """A toy composed adapter which gets shutter position and target and sets target."""
 
     _device: Shutter
 
@@ -110,12 +110,12 @@ def __init__(
         host: str = "localhost",
         port: int = 25565,
     ) -> None:
-        """A constructor of the Shutter adapter, which configures the TcpServer
+        """A Shutter which instantiates a TcpServer with configured host and port.
 
         Args:
             device (Device): The device which this adapter is attached to
             raise_interrupt (Callable): A callback to request that the device is
-                updated immediately
+                updated immediately.
             host (Optional[str]): The host address of the TcpServer. Defaults to
                 "localhost".
             port (Optional[int]): The bound port of the TcpServer. Defaults to 25565.
@@ -129,28 +129,28 @@ def __init__(
 
     @RegexCommand(r"P\?", False, "utf-8")
     async def get_position(self) -> bytes:
-        """A regex string command which returns the utf-8 encoded value of position
+        """A regex string command which returns the utf-8 encoded value of position.
 
         Returns:
-            bytes: The utf-8 encoded value of position
+            bytes: The utf-8 encoded value of position.
         """
         return str(self._device.position).encode("utf-8")
 
     @RegexCommand(r"T\?", False, "utf-8")
     async def get_target(self) -> bytes:
-        """A regex string command which returns the utf-8 encoded value of target
+        """A regex string command which returns the utf-8 encoded value of target.
 
         Returns:
-            bytes: The utf-8 encoded value of target
+            bytes: The utf-8 encoded value of target.
         """
         return str(self._device.target_position).encode("utf-8")
 
     @RegexCommand(r"T=(\d+\.?\d*)", True, "utf-8")
     async def set_target(self, target: str) -> None:
-        """A regex string command which sets the target position of the shutter
+        """A regex string command which sets the target position of the shutter.
 
         Args:
-            target (str): The target position of the shutter
+            target (str): The target position of the shutter.
         """
         self._device.target_position = float(target)
         self._device.last_time = None