Update docstrings (#123)

* Update docstring in remote controlled device

* update device update method doc string

* Update doc strings for serialize and deserialize

* Update docstrings in base component

* Update docsting in system simulation run forever

* Update subscribe method docstrings

* Update subscribe method docstring

* Update dependants method docstring

* Update on_tick and update_component docstrings

* Update schedule_interrupt docstring

* Update docstring on run_forever method

* Update on_connect and Handle_message docstrings

* Update message handle docstring

* Update splitting interperter docstrings

* Update sink device docstrings

* Fix formatting issues

* Add google convention to pydocstyle

examples/devices/remote_controlled.py

@@ -47,8 +47,7 @@ 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.
+        """Produces an output mapping containing the observed value.
 
         Args:
             time (SimTime): The current simulation time (in nanoseconds).
@@ -86,8 +85,7 @@ def __init__(
         )
 
     async def on_connect(self) -> AsyncIterable[Optional[bytes]]:
-        """An on_connect method which continiously sends the unobserved value to the
-        client.
+        """Continiously sends the unobserved value to the client.
 
         Returns:
             AsyncIterable[bytes]:

pyproject.toml

@@ -86,6 +86,7 @@ max-line-length = 88 # Respect black's line length (default 88),
 exclude = [".tox", "venv"]
 
 [tool.pydocstyle]
+convention = "google"
 add-ignore = [
     "D100", # Ignore missing docstrings in public modules
     "D104", # Ignore missing docstrings in public packages

src/tickit/adapters/composed.py

@@ -20,8 +20,7 @@ class ComposedAdapter(Adapter, Generic[T]):
     interpreter: Interpreter
 
     async def on_connect(self) -> AsyncIterable[Optional[T]]:
-        """An overridable asynchronous iterable which yields messages on client
-        connection.
+        """Overridable asynchronous iterable which yields messages on client connection.
 
         Returns:
             AsyncIterable[Optional[T]]: An asynchronous iterable of messages.
@@ -30,8 +29,7 @@ async def on_connect(self) -> AsyncIterable[Optional[T]]:
             yield None
 
     async def handle_message(self, message: T) -> AsyncIterable[Optional[T]]:
-        """Delegates message handling to the interpreter and raises interrupt if
-        requested.
+        """Delegates message handling to the interpreter, raises interrupt if requested.
 
         Args:
             message (T): The message from the server to be handled.

src/tickit/adapters/interpreters/wrappers/beheading_interpreter.py

@@ -25,8 +25,7 @@ def __init__(self, interpreter: Interpreter[AnyStr], header_size: int) -> None:
     async def handle(
         self, adapter: Adapter, message: AnyStr
     ) -> Tuple[AsyncIterable[AnyStr], bool]:
-        """Removes a header from the start of a message, and passes it on to an
-        interpreter.
+        """Removes a header from a message and passes the message on to an interpreter.
 
         Args:
             adapter (Adapter): The adapter in which the function should be executed

src/tickit/adapters/interpreters/wrappers/splitting_interpreter.py

@@ -18,8 +18,7 @@ def __init__(
         interpreter: Interpreter[AnyStr],
         message_delimiter: AnyStr,
     ) -> None:
-        """A decorator for an interpreter that splits a message into multiple
-        sub-messages.
+        """An interpreter decorator that splits a message into multiple sub-messages.
 
         Args:
             interpreter (Interpreter): The interpreter messages are passed on to.

src/tickit/core/components/component.py

@@ -123,7 +123,7 @@ async def output(
         )
 
     async def raise_interrupt(self) -> None:
-        """Send an Interrupt message to the component output topic.
+        """Sends an Interrupt message to the component output topic.
 
         An asynchronous method whicb constructs an Interrupt message tagged with the
         component name and sends it to the output topic of this component.
@@ -133,7 +133,7 @@ async def raise_interrupt(self) -> None:
     async def run_forever(
         self, state_consumer: Type[StateConsumer], state_producer: Type[StateProducer]
     ) -> None:
-        """Create and configures a state consumer and state producer.
+        """Creates and configures a state consumer and state producer.
 
         An asynchronous method which creates a state consumer which is subscribed to
         the input topic of the component and calls back to handle_input, and a state
@@ -145,8 +145,7 @@ async def run_forever(
 
     @abstractmethod
     async def on_tick(self, time: SimTime, changes: Changes):
-        """An abstract asynchronous method which implements the core logic of the
-        component.
+        """Abstract asynchronous method which implements core logic of the component.
 
         Args:
             time (SimTime): The current simulation time (in nanoseconds).

src/tickit/core/components/system_simulation.py

@@ -37,8 +37,7 @@ class SystemSimulationComponent(BaseComponent):
     async def run_forever(
         self, state_consumer: Type[StateConsumer], state_producer: Type[StateProducer]
     ) -> None:
-        """Sets up state interfaces, the scheduler, and components and blocks until any
-        complete.
+        """Sets up state interfaces, the scheduler, and components to run continuously.
 
         An asynchronous method starts the run_forever method of each component, runs
         the scheduler, and sets up externally facing state interfaces. The method

src/tickit/core/device.py

@@ -30,8 +30,7 @@ class Device(ABC, Generic[InMap, OutMap]):
 
     @abstractmethod
     def update(self, time: SimTime, inputs: InMap) -> DeviceUpdate[OutMap]:
-        """A method which implements device behaviour according to the time and its
-        inputs.
+        """Implements device behaviour according to the time and its inputs.
 
         A method which implements the (typically physics based) changes which occur
         within the device in response to either the progression of time or the

src/tickit/core/management/event_router.py

@@ -232,7 +232,9 @@ def inverse_component_tree(self) -> Dict[ComponentID, Set[ComponentID]]:
         return inverse_tree
 
     def dependants(self, root: ComponentID) -> Set[ComponentID]:
-        """Finds the set of all components which are recursively dependant on the root
+        """Finds the set of root component dependents .
+
+        Finds the set of all components which are recursively dependant on the root
         component.
 
         Args:

src/tickit/core/management/schedulers/base.py

@@ -48,7 +48,9 @@ def __init__(
 
     @abstractmethod
     async def schedule_interrupt(self, source: ComponentID) -> None:
-        """An abstract asynchronous method which should schedule an interrupt
+        """An abstract asynchronous method which should schedule an interrupt.
+
+        When implemented in a child this method should schedule an interrupt
         immediately.
 
         Args:

src/tickit/core/management/schedulers/master.py

@@ -60,8 +60,7 @@ def add_wakeup(self, component: ComponentID, when: SimTime) -> None:
         self.new_wakeup.set()
 
     async def run_forever(self) -> None:
-        """Performs an intial tick then continiously schedules ticks according to
-        wakeups.
+        """Perform an intial tick then continiously schedule ticks according to wakeups.
 
         An asynchronous method which initially performs setup and an initial tick in
         which all components are updated, subsequently ticks are performed as requested

src/tickit/core/management/schedulers/slave.py

@@ -31,8 +31,7 @@ def __init__(
         expose: Dict[PortID, ComponentPort],
         raise_interrupt: Callable[[], Awaitable[None]],
     ) -> None:
-        """A slave scheduler constructor which adds wiring and saves values for
-        reference.
+        """Slave scheduler constructor which adds wiring and saves values for reference.
 
         Args:
             wiring (Union[Wiring, InverseWiring]): A wiring or inverse wiring object
@@ -81,8 +80,7 @@ def add_exposing_wiring(
         return wiring
 
     async def update_component(self, input: Input) -> None:
-        """Sends an input to the corresponding component. Mocks I/O for "external" or
-        "expose".
+        """Sends an input to the target component. Mocks I/O for "external" or "expose".
 
         For real components the input is sent in a message to their input topic, for
         the mock component named "external", external inputs are injected, whilst for
@@ -107,8 +105,7 @@ async def update_component(self, input: Input) -> None:
     async def on_tick(
         self, time: SimTime, changes: Changes
     ) -> Tuple[Changes, Optional[SimTime]]:
-        """Routes inputs, performs a tick and returns output changes and a callback
-        time.
+        """Routes inputs, does a tick and returns output changes and a callback time.
 
         An asyhcnronous method which determines which components within the simulation
         require being woken up, sets the input changes for use by the "external" mock

src/tickit/core/state_interfaces/internal.py

@@ -64,8 +64,7 @@ async def push(self, topic: str, message: Message) -> None:
             await subscriber.add_message(message)
 
     async def subscribe(self, consumer: "InternalStateConsumer", topics: Iterable[str]):
-        """Subscribes the consumer to the given topics, so it is notified a message is
-        added.
+        """Subscribes the consumer to the given topics.
 
         An asynchronous method which adds a consumer to the subscriber list of each
         topic in the topics iterable. On subscription, previous messages on the topic
@@ -130,7 +129,9 @@ def __init__(self, callback: Callable[[C], Awaitable[None]]) -> None:
         self.callback = callback
 
     async def subscribe(self, topics: Iterable[str]) -> None:
-        """Subscribes the consumer to the given topics, new messages are passed to the
+        """Subscribes the consumer to the given topics.
+
+        Subscribes the consumer to the given topics, new messages are passed to the
         callback.
 
         Args:

src/tickit/core/state_interfaces/kafka.py

@@ -46,7 +46,9 @@ async def _run_forever(self) -> None:
                 await self.callback(message.value)
 
     async def subscribe(self, topics: Iterable[str]):
-        """Subscribes the consumer to the given topics, new messages are passed to the
+        """Subscribes the consumer to the given topics.
+
+        Subscribes the consumer to the given topics, new messages are passed to the
         callback.
 
         Args:

src/tickit/core/typedefs.py

@@ -33,7 +33,9 @@ def __repr__(self) -> str:
 
     @serializer
     def serialize(self) -> str:
-        """An apischema serialization method which returns a string of component:port.
+        """Returns a string of component:port.
+
+        An apischema serialization method which returns a string of component:port.
 
         Returns:
             str: The serialized ComponentPort, in format component:port.
@@ -43,8 +45,10 @@ def serialize(self) -> str:
     @deserializer
     @staticmethod
     def deserialize(data: str) -> "ComponentPort":
-        """An apischema deserialization method which builds a from a string of
-        component:port.
+        """Builds a ComponentPort from a string of component:port.
+
+        An apischema deserialization method which builds a ComponentPort from a string
+        of component:port.
 
         Returns:
             ComponentPort: The deserialized ComponentPort.

src/tickit/devices/sink.py

@@ -19,8 +19,7 @@ class SinkDevice(Device):
     Outputs: TypedDict = TypedDict("Outputs", {})
 
     def update(self, time: SimTime, inputs: Inputs) -> DeviceUpdate[Outputs]:
-        """The update method which logs the inputs at debug level and produces no
-        outputs.
+        """The update method which logs the inputs and produces no outputs.
 
         Args:
             time (SimTime): The current simulation time (in nanoseconds).

src/tickit/utils/configuration/configurable.py

@@ -30,8 +30,7 @@ def rec_subclasses(cls: type) -> Iterator[type]:
 
 
 def as_tagged_union(cls: Cls) -> Cls:
-    """A decorator to make a config base class which can deserialize aliased
-    sub-classes.
+    """A decorator to make a config base class that can deserialize aliased sub-classes.
 
     A decorator which makes a config class the root of a tagged union of sub-classes
     allowing for serialization and deserialization of config trees by class alias. The
@@ -46,8 +45,9 @@ def as_tagged_union(cls: Cls) -> Cls:
         Cls: The modified config base class.
     """
 
-    # This will only be used if we want to generate a json schema (which we will)
-    def deserialization() -> Conversion:
+    def deserialization() -> (
+        Conversion
+    ):  # This will only be used if we want to generate a json schema (which we will)
         annotations: Dict[str, Any] = {}
         deserialization_namespace: Dict[str, Any] = {"__annotations__": annotations}
         for sub in rec_subclasses(cls):