refactor: Event connector UX (#200)

# Summary
This PR addresses #57 by refactoring the code involved in creating
`Connector`s for `Event`s in event-driven models in an attempt to
simplify the user experience. Previously multiple lines of code were
required involving several library classes putting some burden of
understanding low level details on the user. Now these lines can be
replaced with a single line of code involving a concrete `Connector`
class which will be familiar to users.

# Changes
- `EventConnectorBuilder` becomes a utility class
`EventConnectorSpecBuilder` with its responsibility changed to producing
a mapping of `event.type` -> `ConnectorSpec`.
- `ConnectorBuilder` exposes a new method
`build_event_connectors(components: list[Component]) -> list[Connector]`
which consumes the `EventConnectorSpecBuilder` to produce the required
`Event` `Connector`s.
- `Connector` ABC has a new class method `builder` which returns a
`ConnectorBuilder` for a given `Connector` concrete class.
- Updates tests, examples, and docs with this streamlined approach.
- Also corrects the logic related to restricting attempted use of event
based models with `RayConnector` (previously restriction was applied to
`RayProcess` which actually can be used with different `Connector`
classes).

---------

Co-authored-by: Toby Coleman <toby@tobycoleman.com>

Author: chrisk314

docs/api/events/events.md

@@ -4,5 +4,4 @@
       - Event
       - SystemEvent
       - StopEvent
-      - EventConnectorBuilder
       - EventHandlers

docs/examples/tutorials/event-driven-models.md

@@ -66,7 +66,7 @@ Finally, we need components to subscribe to these events and process them. Use t
 Now we can create a [`Process`][plugboard.process.Process] from all these components. The outputs from `CollectLow` and `CollectHigh` are connected to separate [`FileWriter`][plugboard.library.FileWriter] components so that we'll get a CSV file containing the latest high and low values at each step of the simulation.
 
 !!! info
-    We need a few extra lines of code to create connectors for the event-based parts of the model. If you define your process in YAML this will be done automatically for you, but if you are defining the process in code then you will need to use the [`EventConnectorBuilder`][plugboard.events.EventConnectorBuilder] to do this.
+    We need a few extra lines of code to create connectors for the event-based parts of the model. If you define your process in YAML this will be done automatically for you, but if you are defining the process in code then you will need to use the [`ConnectorBuilder`][plugboard.connector.ConnectorBuilder] to do this.
 
 ```python hl_lines="15-17"
 --8<-- "examples/tutorials/005_events/hello_events.py:main"

examples/demos/finance/001_momentum_signal/momentum-signal.ipynb

@@ -69,7 +69,6 @@
     "import typing as _t\n",
     "\n",
     "from plugboard.connector import AsyncioConnector, ConnectorBuilder\n",
-    "from plugboard.events import EventConnectorBuilder\n",
     "from plugboard.process import LocalProcess\n",
     "from plugboard.schemas import ConnectorSpec\n",
     "\n",
@@ -480,9 +479,7 @@
     "]\n",
     "\n",
     "# Event connectors\n",
-    "builder = ConnectorBuilder(connector_cls=AsyncioConnector)\n",
-    "event_builder = EventConnectorBuilder(connector_builder=builder)\n",
-    "event_connectors = list(event_builder.build(components).values())\n",
+    "event_connectors = AsyncioConnector.builder().build_event_connectors(components)\n",
     "\n",
     "process = LocalProcess(components=components, connectors=connectors + event_connectors)"
    ]

examples/demos/llm/004_image_processing/local-and-remote-image-processing.ipynb

@@ -73,7 +73,7 @@
     "from plugboard.schemas import ComponentArgsDict, ConnectorSpec\n",
     "from plugboard.process import LocalProcess\n",
     "from plugboard.library import FileReader, FileWriter, LLMImageProcessor\n",
-    "from plugboard.events import Event, EventConnectorBuilder"
+    "from plugboard.events import Event"
    ]
   },
   {
@@ -390,9 +390,7 @@
     "]\n",
     "\n",
     "# Event Connectors\n",
-    "builder = ConnectorBuilder(connector_cls=AsyncioConnector)\n",
-    "event_builder = EventConnectorBuilder(connector_builder=builder)\n",
-    "event_connectors = list(event_builder.build(components).values())\n",
+    "event_connectors = AsyncioConnector.builder().build_event_connectors(components)\n",
     "\n",
     "# Define Process\n",
     "process = LocalProcess(components=components, connectors=connectors + event_connectors)\n",

examples/tutorials/005_events/hello_events.py

@@ -9,7 +9,7 @@
 
 from plugboard.component import Component, IOController
 from plugboard.connector import AsyncioConnector, ConnectorBuilder
-from plugboard.events import Event, EventConnectorBuilder, StopEvent
+from plugboard.events import Event, StopEvent
 from plugboard.library import FileWriter
 from plugboard.process import LocalProcess
 from plugboard.schemas import ConnectorSpec, ComponentArgsDict
@@ -139,9 +139,7 @@ async def main() -> None:
         connect("collect-high.value", "save-high.value"),
         connect("collect-low.value", "save-low.value"),
     ]
-    connector_builder = ConnectorBuilder(connector_cls=AsyncioConnector)  # (2)!
-    event_connector_builder = EventConnectorBuilder(connector_builder=connector_builder)
-    event_connectors = list(event_connector_builder.build(components).values())
+    event_connectors = AsyncioConnector.builder().build_event_connectors(components)  # (3)!
 
     process = LocalProcess(
         components=components,

plugboard/connector/connector.py

@@ -6,6 +6,7 @@
 import typing as _t
 
 from plugboard.connector.channel import Channel
+from plugboard.connector.connector_builder import ConnectorBuilder
 from plugboard.schemas import ConnectorSpec
 from plugboard.utils import ExportMixin
 
@@ -39,3 +40,8 @@ def dict(self) -> dict[str, _t.Any]:  # noqa: D102
             "id": self.id,
             "spec": self.spec.model_dump(),
         }
+
+    @classmethod
+    def builder(cls, *args: _t.Any, **kwargs: _t.Any) -> ConnectorBuilder:
+        """Returns a `ConnectorBuilder` for this `Connector` class."""
+        return ConnectorBuilder(cls, *args, **kwargs)

plugboard/connector/connector_builder.py

@@ -1,8 +1,14 @@
 """Provides `ConnectorBuilder` to build `Connector` objects."""
 
+from __future__ import annotations
+
 import typing as _t
 
-from plugboard.connector.connector import Connector
+
+if _t.TYPE_CHECKING:  # pragma: no cover
+    from plugboard.connector.connector import Connector
+
+from plugboard.connector.event_connector_spec_builder import EventConnectorSpecBuilder
 from plugboard.schemas import ConnectorSpec
 
 
@@ -17,3 +23,8 @@ def __init__(self, connector_cls: type[Connector], *args: _t.Any, **kwargs: _t.A
     def build(self, spec: ConnectorSpec) -> Connector:
         """Builds a `Connector` object."""
         return self._connector_cls(spec, *self._args, **self._kwargs)
+
+    def build_event_connectors(self, components: _t.Iterable[_t.Any]) -> list[Connector]:
+        """Builds event connectors for the given components."""
+        evt_conn_map = EventConnectorSpecBuilder.build(components)
+        return [self.build(spec=spec) for spec in evt_conn_map.values()]

plugboard/connector/event_connector_spec_builder.py

@@ -0,0 +1,53 @@
+"""Provides `EventConnectorSpecBuilder` utility class which builds event connector specs for components."""  # noqa: E501,W505
+
+from __future__ import annotations
+
+import typing as _t
+
+from plugboard.events.event import Event
+from plugboard.schemas import ConnectorMode, ConnectorSocket, ConnectorSpec
+
+
+if _t.TYPE_CHECKING:
+    from plugboard.component import Component
+
+
+class EventConnectorSpecBuilder:  # pragma: no cover
+    """`EventConnectorSpecBuilder` constructs connector specs for component event handlers."""
+
+    _source_descriptor: str = "publishers"
+    _target_descriptor: str = "subscribers"
+
+    @staticmethod
+    def build(components: _t.Iterable[Component]) -> dict[str, ConnectorSpec]:
+        """Returns mapping of connector specs for events handled by components."""
+        evt_conn_map: dict[str, ConnectorSpec] = {}
+        for component in components:
+            comp_evt_conn_map = EventConnectorSpecBuilder._build_for_component(
+                evt_conn_map, component
+            )
+            evt_conn_map.update(comp_evt_conn_map)
+        return evt_conn_map
+
+    @staticmethod
+    def _build_for_component(
+        evt_conn_map: dict[str, ConnectorSpec], component: Component
+    ) -> dict[str, ConnectorSpec]:
+        component_evts = set(component.io.input_events + component.io.output_events)
+        return {
+            evt.type: EventConnectorSpecBuilder._build_for_event(evt.type)
+            for evt in component_evts
+            if evt.type not in evt_conn_map
+        }
+
+    @staticmethod
+    def _build_for_event(evt_type: str) -> ConnectorSpec:
+        evt_type_safe = Event.safe_type(evt_type)
+        source = ConnectorSocket(
+            entity=evt_type_safe, descriptor=EventConnectorSpecBuilder._source_descriptor
+        )
+        target = ConnectorSocket(
+            entity=evt_type_safe, descriptor=EventConnectorSpecBuilder._target_descriptor
+        )
+        spec = ConnectorSpec(source=source, target=target, mode=ConnectorMode.PUBSUB)
+        return spec

plugboard/events/__init__.py

@@ -1,13 +1,11 @@
 """Provides models and utilities for handling events."""
 
 from plugboard.events.event import Event, StopEvent, SystemEvent
-from plugboard.events.event_connector_builder import EventConnectorBuilder
 from plugboard.events.event_handlers import EventHandlers
 
 
 __all__ = [
     "Event",
-    "EventConnectorBuilder",
     "EventHandlers",
     "StopEvent",
     "SystemEvent",