onesecondtrader 0.49.0__py3-none-any.whl → 0.50.0__py3-none-any.whl

onesecondtrader/messaging/__init__.py

@@ -0,0 +1,11 @@
+"""
+Provides the infrastructure for event-based communication between system components.
+"""
+
+from .eventbus import EventBus
+from .subscriber import Subscriber
+
+__all__ = [
+    "EventBus",
+    "Subscriber",
+]

onesecondtrader/messaging/eventbus.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import collections
+import threading
+import typing
+
+from onesecondtrader import events
+
+if typing.TYPE_CHECKING:
+    from .subscriber import Subscriber
+
+
+class EventBus:
+    """
+    Event dispatch mechanism for propagating event objects to subscribers.
+
+    The event bus maintains subscriptions between subscribers and concrete event types.
+    Events published to the bus are synchronously delivered to all subscribers registered for the exact event type.
+
+    Subscription management and event publication are thread-safe.
+    Event delivery itself occurs outside the internal lock.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize an empty event bus.
+
+        The bus starts with no registered subscribers and no active subscriptions.
+        """
+        self._per_event_subscriptions: collections.defaultdict[
+            type[events.EventBase], set[Subscriber]
+        ] = collections.defaultdict(set)
+        self._subscribers: set[Subscriber] = set()
+        self._lock: threading.Lock = threading.Lock()
+
+    def subscribe(
+        self,
+        subscriber: Subscriber,
+        event_type: type[events.EventBase],
+    ) -> None:
+        """
+        Register a subscriber for a specific event type.
+
+        The subscriber will receive all future events whose concrete type matches `event_type`.
+
+        Parameters:
+            subscriber:
+                Object receiving published events.
+            event_type:
+                Concrete event class the subscriber is interested in.
+        """
+        with self._lock:
+            self._subscribers.add(subscriber)
+            self._per_event_subscriptions[event_type].add(subscriber)
+
+    def unsubscribe(self, subscriber: Subscriber) -> None:
+        """
+        Remove a subscriber from all event subscriptions.
+
+        After unsubscription, the subscriber will no longer receive any events published on this bus.
+
+        Parameters:
+            subscriber:
+                Subscriber to remove.
+        """
+        with self._lock:
+            for set_of_event_subscribers in self._per_event_subscriptions.values():
+                set_of_event_subscribers.discard(subscriber)
+            self._subscribers.discard(subscriber)
+
+    def publish(self, event: events.EventBase) -> None:
+        """
+        Publish an event to all subscribed listeners.
+
+        Subscribers are matched strictly by the concrete type of the event.
+        Parent classes and inheritance relationships are not considered.
+
+        Parameters:
+            event:
+                Event instance to dispatch.
+        """
+        with self._lock:
+            subscribers = self._per_event_subscriptions[type(event)].copy()
+        for subscriber in subscribers:
+            subscriber.receive(event)
+
+    def wait_until_system_idle(self) -> None:
+        """
+        Block until all subscribers report an idle state.
+
+        This method delegates to each subscriber's `wait_until_idle` method and returns only after all subscribers have completed any pending work.
+        """
+        with self._lock:
+            subscribers = self._subscribers.copy()
+        for subscriber in subscribers:
+            subscriber.wait_until_idle()

onesecondtrader/messaging/subscriber.py

@@ -0,0 +1,153 @@
+import abc
+import queue
+import threading
+
+from onesecondtrader import events, messaging
+
+
+class Subscriber(abc.ABC):
+    """
+    Abstract base class for event bus subscribers.
+
+    A subscriber receives events from an event bus and processes them asynchronously in a dedicated worker thread.
+    Incoming events are queued and handled sequentially.
+
+    Subclasses implement `_on_event` to define event-specific behavior.
+    """
+
+    def __init__(self, event_bus: messaging.EventBus) -> None:
+        """
+        Initialize the subscriber and start its event-processing thread.
+
+        Parameters:
+            event_bus:
+                Event bus used for subscribing to and publishing events.
+        """
+        self._event_bus = event_bus
+        self._queue: queue.Queue[events.EventBase | None] = queue.Queue()
+
+        self._running: threading.Event = threading.Event()
+        self._running.set()
+
+        self._thread = threading.Thread(
+            target=self._event_loop, name=self.__class__.__name__
+        )
+        self._thread.start()
+
+    def receive(self, event: events.EventBase) -> None:
+        """
+        Receive an event from the event bus.
+
+        The event is enqueued for asynchronous processing if the subscriber is running.
+
+        Parameters:
+            event:
+                Event instance delivered by the event bus.
+        """
+        if self._running.is_set():
+            self._queue.put(event)
+
+    def wait_until_idle(self) -> None:
+        """
+        Block until all queued events have been processed.
+
+        If the subscriber is not running, this method returns immediately.
+        """
+        if not self._running.is_set():
+            return
+
+        self._queue.join()
+
+    def shutdown(self) -> None:
+        """
+        Shut down the subscriber and stop event processing.
+
+        The subscriber is unsubscribed from the event bus, its worker thread is signaled to terminate, and all pending events are processed before shutdown completes.
+        """
+        if not self._running.is_set():
+            return
+
+        self._event_bus.unsubscribe(self)
+        self._running.clear()
+        self._queue.put(None)
+
+        if threading.current_thread() is not self._thread:
+            self._thread.join()
+
+    def _subscribe(self, *event_types: type[events.EventBase]) -> None:
+        """
+        Subscribe this subscriber to one or more event types.
+
+        Parameters:
+            *event_types:
+                Concrete event classes to subscribe to.
+        """
+        for event_type in event_types:
+            self._event_bus.subscribe(self, event_type)
+
+    def _publish(self, event: events.EventBase) -> None:
+        """
+        Publish an event to the event bus.
+
+        Parameters:
+            event:
+                Event instance to publish.
+        """
+        self._event_bus.publish(event)
+
+    def _event_loop(self) -> None:
+        """
+        Internal worker loop for processing queued events.
+
+        This method runs in a dedicated thread and should not be called directly.
+        """
+        while True:
+            event = self._queue.get()
+
+            if event is None:
+                self._queue.task_done()
+                break
+
+            try:
+                self._on_event(event)
+            except Exception as exc:
+                self._on_exception(exc)
+            finally:
+                self._queue.task_done()
+
+        self._cleanup()
+
+    def _on_exception(self, exc: Exception) -> None:
+        """
+        Handle an exception raised during event processing.
+
+        Subclasses may override this method to implement logging or recovery behavior.
+        The default implementation ignores the exception.
+
+        Parameters:
+            exc:
+                Exception raised while processing an event.
+        """
+        pass
+
+    def _cleanup(self) -> None:
+        """
+        Perform cleanup after the event loop terminates.
+
+        Subclasses may override this method to release resources or emit shutdown notifications.
+        """
+        pass
+
+    @abc.abstractmethod
+    def _on_event(self, event: events.EventBase) -> None:
+        """
+        Handle a single event.
+
+        This method is invoked sequentially for each event received by the subscriber.
+        Implementations must not block indefinitely, as `wait_until_idle` relies on timely completion.
+
+        Parameters:
+            event:
+                Event instance to handle.
+        """
+        ...

{onesecondtrader-0.49.0.dist-info → onesecondtrader-0.50.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onesecondtrader
-Version: 0.49.0
+Version: 0.50.0
 Summary: The Trading Infrastructure Toolkit for Python. Research, simulate, and deploy algorithmic trading strategies — all in one place.
 License-File: LICENSE
 Author: Nils P. Kujath

{onesecondtrader-0.49.0.dist-info → onesecondtrader-0.50.0.dist-info}/RECORD

@@ -22,13 +22,16 @@ onesecondtrader/indicators/__init__.py,sha256=i-syRqCdQdC2BLL-7bDBcdl2Mll1LgE7hi
 onesecondtrader/indicators/base.py,sha256=iGfgOj1B_LRGBeh7VjM5OjxoYnSxV7JZUP1C3O_dfmE,4653
 onesecondtrader/indicators/market_fields.py,sha256=Znyii0egBkJT3CFlYhQ5ArRNidmBLF0TzgCr2AWu5CA,4306
 onesecondtrader/indicators/moving_averages.py,sha256=Ej3Vg-K4Kf93J3MS6av2J8FRP1Kqx4G6yNZj1QfE9lU,3411
+onesecondtrader/messaging/__init__.py,sha256=VIVxQmJR3E50AuAze50CHIygRHJSwg26fC3ZBkiUnbQ,209
+onesecondtrader/messaging/eventbus.py,sha256=l010Sh57ti9y-R1E8fa597YmoC5c40vR_oyu0eTKEjg,3234
+onesecondtrader/messaging/subscriber.py,sha256=KDtUNipe0dXl05ClIeQevIK2V7u5A4O-P84kpfS_Y28,4479
 onesecondtrader/models/__init__.py,sha256=XWL6aNLwAA2JQMoqK2PY-_CwigV0ighx4zwGQVdmtCs,529
 onesecondtrader/models/bar_fields.py,sha256=GnLBL08ueUr35w2dAbKwOBWrdBS98OC9r0T2NifwTH8,646
 onesecondtrader/models/bar_period.py,sha256=J8ncVtcAxR52uD0nbC8Knds_GUP5wiuNj5rAKq4vv-4,475
 onesecondtrader/models/order_types.py,sha256=SiJamarLQ7zkHzHLLbd86I_TeZrQJ4QEIMqNHj4dxXU,737
 onesecondtrader/models/rejection_reasons.py,sha256=BToLmPholsP9GcLGZ874nQJpehZ1yB1SFyYqlf3AOwc,2127
 onesecondtrader/models/trade_sides.py,sha256=Pf9BpxoUxqgKC_EKAExfSqgfIIK9NW-RpJES0XHRF-8,583
-onesecondtrader-0.49.0.dist-info/METADATA,sha256=EFqtCI8r8EWYjn-l1LOkaWIsF0QrUZyq1UFA2WI56Dk,9951
-onesecondtrader-0.49.0.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
-onesecondtrader-0.49.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-onesecondtrader-0.49.0.dist-info/RECORD,,
+onesecondtrader-0.50.0.dist-info/METADATA,sha256=osrTVFj2ZqYZwPeBnaMBkRnfbfZaBIcl9YDpBhyrD-U,9951
+onesecondtrader-0.50.0.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+onesecondtrader-0.50.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+onesecondtrader-0.50.0.dist-info/RECORD,,