onesecondtrader 0.49.0__tar.gz → 0.51.0__tar.gz

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onesecondtrader
-Version: 0.49.0
+Version: 0.51.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 → onesecondtrader-0.51.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "onesecondtrader"
-version = "0.49.0"
+version = "0.51.0"
 description = "The Trading Infrastructure Toolkit for Python. Research, simulate, and deploy algorithmic trading strategies — all in one place."
 authors = [
     {name = "Nils P. Kujath",email = "63961429+NilsKujath@users.noreply.github.com"}

onesecondtrader-0.51.0/src/onesecondtrader/brokers/__init__.py

@@ -0,0 +1,11 @@
+"""
+Provides interfaces for order execution via a simulated broker and adapters to real venues.
+"""
+
+from onesecondtrader.brokers.base import BrokerBase
+from onesecondtrader.brokers.simulated import SimulatedBroker
+
+__all__ = [
+    "BrokerBase",
+    "SimulatedBroker",
+]

onesecondtrader-0.51.0/src/onesecondtrader/brokers/base.py

@@ -0,0 +1,110 @@
+import abc
+
+from onesecondtrader import events, messaging
+
+
+class BrokerBase(messaging.Subscriber):
+    """
+    Abstract base class for broker components.
+
+    A broker component receives order-related request events from the event bus and translates them into actions against an external execution venue or simulated environment.
+    Responses to these requests are published back onto the event bus.
+
+    This class defines the event-handling interface and subscription logic common to all broker implementations.
+    """
+
+    def __init__(self, event_bus: messaging.EventBus) -> None:
+        """
+        Initialize the broker and subscribe to order request events.
+
+        Parameters:
+            event_bus:
+                Event bus used for receiving order requests and publishing response events.
+        """
+        super().__init__(event_bus)
+
+        self._subscribe(
+            events.requests.OrderSubmissionRequest,
+            events.requests.OrderCancellationRequest,
+            events.requests.OrderModificationRequest,
+        )
+
+    @abc.abstractmethod
+    def connect(self) -> None:
+        """
+        Establish a connection to the external broker API.
+        For simulated broker, this method is a no-op.
+
+        Implementations are responsible for initializing any external resources required to submit, modify, or cancel orders.
+        """
+        pass
+
+    def disconnect(self) -> None:
+        """
+        Disconnect the external broker API and stop event processing.
+        For simulated broker, this method is a no-op.
+
+        This method shuts down the subscriber and releases associated resources.
+        """
+        self.shutdown()
+
+    def _on_event(self, event: events.EventBase) -> None:
+        """
+        Dispatch incoming order-related events to the appropriate handler.
+
+        Parameters:
+            event:
+                Incoming event received from the event bus.
+        """
+        match event:
+            case events.requests.OrderSubmissionRequest() as submit_order:
+                self._on_submit_order(submit_order)
+            case events.requests.OrderCancellationRequest() as cancel_order:
+                self._on_cancel_order(cancel_order)
+            case events.requests.OrderModificationRequest() as modify_order:
+                self._on_modify_order(modify_order)
+            case _:
+                return
+
+    @abc.abstractmethod
+    def _on_submit_order(self, event: events.requests.OrderSubmissionRequest) -> None:
+        """
+        Handle an order submission request.
+
+        Parameters:
+            event:
+                Order submission request event.
+        """
+        pass
+
+    @abc.abstractmethod
+    def _on_cancel_order(self, event: events.requests.OrderCancellationRequest) -> None:
+        """
+        Handle an order cancellation request.
+
+        Parameters:
+            event:
+                Order cancellation request event.
+        """
+        pass
+
+    @abc.abstractmethod
+    def _on_modify_order(self, event: events.requests.OrderModificationRequest) -> None:
+        """
+        Handle an order modification request.
+
+        Parameters:
+            event:
+                Order modification request event.
+        """
+        pass
+
+    def _respond(self, response_event: events.responses.ResponseBase) -> None:
+        """
+        Publish a response event to the event bus.
+
+        Parameters:
+            response_event:
+                Response event generated by the broker.
+        """
+        self._publish(response_event)

onesecondtrader-0.51.0/src/onesecondtrader/brokers/simulated.py

@@ -0,0 +1,494 @@
+from __future__ import annotations
+
+import dataclasses
+import uuid
+
+from onesecondtrader import events, messaging, models
+from onesecondtrader.brokers.base import BrokerBase
+
+
+@dataclasses.dataclass
+class _PendingOrder:
+    """
+    Internal order state tracked by the simulated broker.
+
+    This structure represents broker-side pending order state and is distinct from order request events.
+    It is used to evaluate trigger conditions against incoming market bars and to generate fills when conditions are met.
+    """
+
+    order_id: uuid.UUID
+    symbol: str
+    order_type: models.OrderType
+    side: models.TradeSide
+    quantity: float
+    limit_price: float | None = None
+    stop_price: float | None = None
+
+
+class SimulatedBroker(BrokerBase):
+    """
+    Event-driven simulated broker for backtesting.
+
+    The broker subscribes to order request events and market bar events.
+    Order requests are validated and accepted or rejected immediately.
+    Accepted orders are stored as pending broker-side state and evaluated against each incoming
+    bar.
+    When an order triggers, a fill event is published with a deterministic fill price model based on the bar's OHLC values.
+
+    The broker publishes response events using the event timestamp to preserve simulated time consistency.
+    """
+
+    commission_per_unit: float = 0.0
+    minimum_commission_per_order: float = 0.0
+
+    def __init__(self, event_bus: messaging.EventBus) -> None:
+        """
+        parameters:
+            event_bus:
+                Event bus used to receive order requests and market bars, and to publish broker responses and fills.
+        """
+        self._pending_market_orders: dict[uuid.UUID, _PendingOrder] = {}
+        self._pending_limit_orders: dict[uuid.UUID, _PendingOrder] = {}
+        self._pending_stop_orders: dict[uuid.UUID, _PendingOrder] = {}
+        self._pending_stop_limit_orders: dict[uuid.UUID, _PendingOrder] = {}
+
+        super().__init__(event_bus)
+        self._subscribe(events.market.BarReceived)
+
+    def connect(self) -> None:
+        """
+        Establish broker readiness.
+
+        The simulated broker has no external connectivity requirements.
+        This method is a no-op and exists to satisfy the broker interface.
+        """
+        pass
+
+    def _on_event(self, event: events.EventBase) -> None:
+        """
+        Dispatch incoming events.
+
+        Market bar events are routed to bar processing.
+        All other events are delegated to the broker base class for order request handling.
+
+        parameters:
+            event:
+                Incoming event received from the event bus.
+        """
+        match event:
+            case events.market.BarReceived() as bar:
+                self._on_bar(bar)
+            case _:
+                super()._on_event(event)
+
+    def _on_bar(self, event: events.market.BarReceived) -> None:
+        """
+        Process an incoming market bar.
+
+        Pending orders are evaluated against the bar in a fixed sequence to provide deterministic behavior.
+        Crucially, limit orders are processed after stop limit orders to ensure that limit orders created by stop limit orders are evaluated against the same bar.
+
+        parameters:
+            event:
+                Market bar used to trigger and price simulated fills.
+        """
+        self._process_market_orders(event)
+        self._process_stop_orders(event)
+        self._process_stop_limit_orders(event)
+        self._process_limit_orders(event)
+
+    def _process_market_orders(self, event: events.market.BarReceived) -> None:
+        """
+        Fill pending market orders for the bar symbol.
+
+        Market orders are filled at the bar open price on the next received bar for the matching symbol.
+
+        parameters:
+            event:
+                Market bar providing the simulated fill price and timestamps.
+        """
+        for order_id, order in list(self._pending_market_orders.items()):
+            if order.symbol != event.symbol:
+                continue
+
+            self._publish(
+                events.orders.FillEvent(
+                    ts_event_ns=event.ts_event_ns,
+                    ts_broker_ns=event.ts_event_ns,
+                    associated_order_id=order.order_id,
+                    symbol=order.symbol,
+                    side=order.side,
+                    quantity_filled=order.quantity,
+                    fill_price=event.open,
+                    commission=max(
+                        order.quantity * self.commission_per_unit,
+                        self.minimum_commission_per_order,
+                    ),
+                )
+            )
+            del self._pending_market_orders[order_id]
+
+    def _process_stop_orders(self, event: events.market.BarReceived) -> None:
+        """
+        Evaluate and fill pending stop orders for the bar symbol.
+
+        Stop orders trigger when the bar crosses the stop level.
+        The fill price is modeled as the worse of the stop price and the bar open in the direction of the trade.
+
+        parameters:
+            event:
+                Market bar used to evaluate triggers and determine fill prices.
+        """
+        for order_id, order in list(self._pending_stop_orders.items()):
+            if order.symbol != event.symbol:
+                continue
+
+            # This is for mypy, it has already been validated on submission
+            assert order.stop_price is not None
+
+            triggered = False
+            match order.side:
+                case models.TradeSide.BUY:
+                    triggered = event.high >= order.stop_price
+                case models.TradeSide.SELL:
+                    triggered = event.low <= order.stop_price
+
+            if not triggered:
+                continue
+
+            fill_price = 0.0
+            match order.side:
+                case models.TradeSide.BUY:
+                    fill_price = max(order.stop_price, event.open)
+                case models.TradeSide.SELL:
+                    fill_price = min(order.stop_price, event.open)
+
+            self._publish(
+                events.orders.FillEvent(
+                    ts_event_ns=event.ts_event_ns,
+                    ts_broker_ns=event.ts_event_ns,
+                    associated_order_id=order.order_id,
+                    symbol=order.symbol,
+                    side=order.side,
+                    quantity_filled=order.quantity,
+                    fill_price=fill_price,
+                    commission=max(
+                        order.quantity * self.commission_per_unit,
+                        self.minimum_commission_per_order,
+                    ),
+                )
+            )
+            del self._pending_stop_orders[order_id]
+
+    def _process_stop_limit_orders(self, event: events.market.BarReceived) -> None:
+        """
+        Evaluate pending stop-limit orders for the bar symbol.
+
+        Stop-limit orders trigger on stop conditions.
+        When triggered, they are converted into pending limit orders at the same identifier.
+
+        parameters:
+            event:
+                Market bar used to evaluate stop triggers.
+        """
+        for order_id, order in list(self._pending_stop_limit_orders.items()):
+            if order.symbol != event.symbol:
+                continue
+
+            assert order.stop_price is not None
+
+            triggered = False
+            match order.side:
+                case models.TradeSide.BUY:
+                    triggered = event.high >= order.stop_price
+                case models.TradeSide.SELL:
+                    triggered = event.low <= order.stop_price
+
+            if not triggered:
+                continue
+
+            limit_order = dataclasses.replace(order, order_type=models.OrderType.LIMIT)
+            self._pending_limit_orders[order_id] = limit_order
+            del self._pending_stop_limit_orders[order_id]
+
+    def _process_limit_orders(self, event: events.market.BarReceived) -> None:
+        """
+        Evaluate and fill pending limit orders for the bar symbol.
+
+        Limit orders trigger when the bar crosses the limit level.
+        The fill price is modeled as the better of the limit price and the bar open in the direction of the trade.
+
+        parameters:
+            event:
+                Market bar used to evaluate triggers and determine fill prices.
+        """
+        for order_id, order in list(self._pending_limit_orders.items()):
+            if order.symbol != event.symbol:
+                continue
+
+            assert order.limit_price is not None
+
+            triggered = False
+            match order.side:
+                case models.TradeSide.BUY:
+                    triggered = event.low <= order.limit_price
+                case models.TradeSide.SELL:
+                    triggered = event.high >= order.limit_price
+
+            if not triggered:
+                continue
+
+            fill_price = 0.0
+            match order.side:
+                case models.TradeSide.BUY:
+                    fill_price = min(order.limit_price, event.open)
+                case models.TradeSide.SELL:
+                    fill_price = max(order.limit_price, event.open)
+
+            self._publish(
+                events.orders.FillEvent(
+                    ts_event_ns=event.ts_event_ns,
+                    ts_broker_ns=event.ts_event_ns,
+                    associated_order_id=order.order_id,
+                    symbol=order.symbol,
+                    side=order.side,
+                    quantity_filled=order.quantity,
+                    fill_price=fill_price,
+                    commission=max(
+                        order.quantity * self.commission_per_unit,
+                        self.minimum_commission_per_order,
+                    ),
+                )
+            )
+            del self._pending_limit_orders[order_id]
+
+    def _reject_if_invalid_submission(
+        self, event: events.requests.OrderSubmissionRequest
+    ) -> bool:
+        """
+        Validate an order submission request.
+
+        Invalid submissions are rejected immediately by publishing an `OrderRejected` response event.
+
+        parameters:
+            event:
+                Order submission request event to validate.
+
+        returns:
+            True if the submission is invalid and was rejected, otherwise False.
+        """
+        is_invalid = event.quantity <= 0
+
+        match event.order_type:
+            case models.OrderType.LIMIT:
+                is_invalid = (
+                    is_invalid or event.limit_price is None or event.limit_price <= 0
+                )
+            case models.OrderType.STOP:
+                is_invalid = (
+                    is_invalid or event.stop_price is None or event.stop_price <= 0
+                )
+            case models.OrderType.STOP_LIMIT:
+                is_invalid = is_invalid or (
+                    event.limit_price is None
+                    or event.limit_price <= 0
+                    or event.stop_price is None
+                    or event.stop_price <= 0
+                )
+
+        if is_invalid:
+            self._publish(
+                events.responses.OrderRejected(
+                    ts_event_ns=event.ts_event_ns,
+                    ts_broker_ns=event.ts_event_ns,
+                    associated_order_id=event.system_order_id,
+                    rejection_reason=models.OrderRejectionReason.UNKNOWN,
+                    rejection_message="Unknown",
+                )
+            )
+
+        return is_invalid
+
+    def _on_submit_order(self, event: events.requests.OrderSubmissionRequest) -> None:
+        """
+        Handle an order submission request.
+
+        Valid orders are stored as pending broker-side state and acknowledged via an `OrderAccepted` response event.
+
+        parameters:
+            event:
+                Order submission request event.
+        """
+        if self._reject_if_invalid_submission(event):
+            return
+
+        order = _PendingOrder(
+            order_id=event.system_order_id,
+            symbol=event.symbol,
+            order_type=event.order_type,
+            side=event.side,
+            quantity=event.quantity,
+            limit_price=event.limit_price,
+            stop_price=event.stop_price,
+        )
+
+        match order.order_type:
+            case models.OrderType.MARKET:
+                self._pending_market_orders[order.order_id] = order
+            case models.OrderType.LIMIT:
+                self._pending_limit_orders[order.order_id] = order
+            case models.OrderType.STOP:
+                self._pending_stop_orders[order.order_id] = order
+            case models.OrderType.STOP_LIMIT:
+                self._pending_stop_limit_orders[order.order_id] = order
+
+        self._publish(
+            events.responses.OrderAccepted(
+                ts_event_ns=event.ts_event_ns,
+                ts_broker_ns=event.ts_event_ns,
+                associated_order_id=order.order_id,
+            )
+        )
+
+    def _on_cancel_order(self, event: events.requests.OrderCancellationRequest) -> None:
+        """
+        Handle an order cancellation request.
+
+        If the referenced order is pending, it is removed and acknowledged via `CancellationAccepted`.
+        Otherwise, `CancellationRejected` is published.
+
+        parameters:
+            event:
+                Order cancellation request event.
+        """
+        order_id = event.system_order_id
+
+        removed = False
+        for pending_orders in (
+            self._pending_market_orders,
+            self._pending_limit_orders,
+            self._pending_stop_orders,
+            self._pending_stop_limit_orders,
+        ):
+            if order_id in pending_orders:
+                del pending_orders[order_id]
+                removed = True
+                break
+
+        if removed:
+            self._publish(
+                events.responses.CancellationAccepted(
+                    ts_event_ns=event.ts_event_ns,
+                    ts_broker_ns=event.ts_event_ns,
+                    associated_order_id=order_id,
+                )
+            )
+        else:
+            self._publish(
+                events.responses.CancellationRejected(
+                    ts_event_ns=event.ts_event_ns,
+                    ts_broker_ns=event.ts_event_ns,
+                    associated_order_id=order_id,
+                    rejection_reason=models.CancellationRejectionReason.UNKNOWN,
+                    rejection_message="Unknown",
+                )
+            )
+
+    def _reject_if_invalid_modification(
+        self, event: events.requests.OrderModificationRequest
+    ) -> bool:
+        """
+        Validate an order modification request.
+
+        Invalid modifications are rejected immediately by publishing a `ModificationRejected` response event.
+
+        parameters:
+            event:
+                Order modification request event to validate.
+
+        returns:
+            True if the modification is invalid and was rejected, otherwise False.
+        """
+        is_invalid = (
+            (event.quantity is not None and event.quantity <= 0)
+            or (event.limit_price is not None and event.limit_price <= 0)
+            or (event.stop_price is not None and event.stop_price <= 0)
+        )
+
+        if is_invalid:
+            self._publish(
+                events.responses.ModificationRejected(
+                    ts_event_ns=event.ts_event_ns,
+                    ts_broker_ns=event.ts_event_ns,
+                    associated_order_id=event.system_order_id,
+                    rejection_reason=models.ModificationRejectionReason.UNKNOWN,
+                    rejection_message="Unknown",
+                )
+            )
+
+        return is_invalid
+
+    def _on_modify_order(self, event: events.requests.OrderModificationRequest) -> None:
+        """
+        Handle an order modification request.
+
+        If the referenced order is pending, its fields are updated and acknowledged via `ModificationAccepted`.
+        Otherwise, `ModificationRejected` is published.
+
+        parameters:
+            event:
+                Order modification request event.
+        """
+        if self._reject_if_invalid_modification(event):
+            return
+
+        order_id = event.system_order_id
+
+        for pending_orders in (
+            self._pending_market_orders,
+            self._pending_limit_orders,
+            self._pending_stop_orders,
+            self._pending_stop_limit_orders,
+        ):
+            if order_id in pending_orders:
+                order = pending_orders[order_id]
+
+                new_quantity = (
+                    event.quantity if event.quantity is not None else order.quantity
+                )
+                new_limit_price = (
+                    event.limit_price
+                    if event.limit_price is not None
+                    else order.limit_price
+                )
+                new_stop_price = (
+                    event.stop_price
+                    if event.stop_price is not None
+                    else order.stop_price
+                )
+
+                pending_orders[order_id] = dataclasses.replace(
+                    order,
+                    quantity=new_quantity,
+                    limit_price=new_limit_price,
+                    stop_price=new_stop_price,
+                )
+
+                self._publish(
+                    events.responses.ModificationAccepted(
+                        ts_event_ns=event.ts_event_ns,
+                        ts_broker_ns=event.ts_event_ns,
+                        associated_order_id=order_id,
+                    )
+                )
+                return
+
+        self._publish(
+            events.responses.ModificationRejected(
+                ts_event_ns=event.ts_event_ns,
+                ts_broker_ns=event.ts_event_ns,
+                associated_order_id=order_id,
+                rejection_reason=models.ModificationRejectionReason.UNKNOWN,
+                rejection_message="Unknown",
+            )
+        )

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/src/onesecondtrader/events/orders/base.py

@@ -9,17 +9,17 @@ from onesecondtrader import events
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class OrderBase(events.EventBase):
     """
-    Base class for broker-originated order events.
+    Base class for brokers-originated order events.
 
-    Order events are broker-originated facts about the state or execution of an order.
+    Order events are brokers-originated facts about the state or execution of an order.
     Each order event is correlated to a system order identifier via `associated_order_id`.
 
     | Field                 | Type            | Semantics                                                                             |
     |-----------------------|-----------------|---------------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`           | Time at which the response event was observed by the system, as UTC epoch nanoseconds.|
     | `ts_created_ns`       | `int`           | Time at which the event object was created, as UTC epoch nanoseconds.                 |
-    | `ts_broker_ns`        | `int`           | Time reported by the broker for the response, as UTC epoch nanoseconds.               |
-    | `associated_order_id` | `uuid.UUID`.    | Identifier of the order associated with the broker response.                          |
+    | `ts_broker_ns`        | `int`           | Time reported by the brokers for the response, as UTC epoch nanoseconds.               |
+    | `associated_order_id` | `uuid.UUID`.    | Identifier of the order associated with the brokers response.                          |
     | `broker_order_id`     | `str` or `None` | Broker-assigned identifier of the order, if reported.                                 |
     | `symbol`              | `str`           | Identifier of the traded instrument.                                                  |
     """

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/src/onesecondtrader/events/orders/expirations.py

@@ -8,13 +8,13 @@ from onesecondtrader.events.orders.base import OrderBase
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class OrderExpired(OrderBase):
     """
-    Event indicating that the order is no longer active at the venue due to expiration according to broker- or venue-specific rules (e.g. time-in-force constraints).
+    Event indicating that the order is no longer active at the venue due to expiration according to brokers- or venue-specific rules (e.g. time-in-force constraints).
 
     | Field                 | Type            | Semantics                                                                          |
     |-----------------------|-----------------|------------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`           | Time at which the expiration was observed by the system, as UTC epoch nanoseconds. |
     | `ts_created_ns`       | `int`           | Time at which the event object was created, as UTC epoch nanoseconds.              |
-    | `ts_broker_ns`        | `int`           | Time reported by the broker for the expiration, as UTC epoch nanoseconds.          |
+    | `ts_broker_ns`        | `int`           | Time reported by the brokers for the expiration, as UTC epoch nanoseconds.          |
     | `associated_order_id` | `uuid.UUID`     | Identifier of the expired order.                                                   |
     | `broker_order_id`     | `str` or `None` | Broker-assigned identifier of the expired order, if reported.                      |
     | `symbol`              | `str`           | Identifier of the traded instrument.                                               |

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/src/onesecondtrader/events/orders/fills.py

@@ -19,7 +19,7 @@ class FillEvent(OrderBase):
     |-----------------------|---------------------|---------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`               | Time at which the fill was observed by the system, as UTC epoch nanoseconds.    |
     | `ts_created_ns`       | `int`               | Time at which the event object was created, as UTC epoch nanoseconds.           |
-    | `ts_broker_ns`        | `int`               | Time reported by the broker for the fill, as UTC epoch nanoseconds.             |
+    | `ts_broker_ns`        | `int`               | Time reported by the brokers for the fill, as UTC epoch nanoseconds.             |
     | `associated_order_id` | `uuid.UUID`         | Identifier of the order associated with the fill.                               |
     | `broker_order_id`     | `str` or `None`     | Broker-assigned identifier of the order associated with the fill, if available. |
     | `symbol`              | `str`               | Identifier of the traded instrument.                                            |

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/src/onesecondtrader/events/requests/base.py

@@ -11,7 +11,7 @@ class RequestBase(events.EventBase):
     """
     Base class for request events.
 
-    This class defines attributes common to all requests issued to a broker.
+    This class defines attributes common to all requests issued to a brokers.
 
     | Field             | Type        | Semantics                                                                  |
     |-------------------|-------------|----------------------------------------------------------------------------|

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/src/onesecondtrader/events/requests/order_submission.py

@@ -10,7 +10,7 @@ from onesecondtrader.events.requests.base import RequestBase
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class OrderSubmissionRequest(RequestBase):
     """
-    Event representing a request to submit a new order to a broker.
+    Event representing a request to submit a new order to a brokers.
 
     The `system_order_id` is a unique identifier assigned by the system to the order submission request by default at object creation.
 

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/src/onesecondtrader/events/responses/base.py

@@ -10,16 +10,16 @@ from onesecondtrader import events
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class ResponseBase(events.EventBase):
     """
-    Base class for broker response events.
+    Base class for brokers response events.
 
-    This class defines attributes common to all responses received from a broker in reaction to previously issued requests.
+    This class defines attributes common to all responses received from a brokers in reaction to previously issued requests.
 
     | Field                 | Type        | Semantics                                                                             |
     |-----------------------|-------------|---------------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`       | Time at which the response event was observed by the system, as UTC epoch nanoseconds.|
     | `ts_created_ns`       | `int`       | Time at which the event object was created, as UTC epoch nanoseconds.                 |
-    | `ts_broker_ns`        | `int`       | Time reported by the broker for the response, as UTC epoch nanoseconds.               |
-    | `associated_order_id` | `uuid.UUID` | Identifier of the order associated with the broker response.                          |
+    | `ts_broker_ns`        | `int`       | Time reported by the brokers for the response, as UTC epoch nanoseconds.               |
+    | `associated_order_id` | `uuid.UUID` | Identifier of the order associated with the brokers response.                          |
     """
 
     ts_broker_ns: int

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/src/onesecondtrader/events/responses/cancellations.py

@@ -9,13 +9,13 @@ from onesecondtrader.events.responses.base import ResponseBase
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class CancellationAccepted(ResponseBase):
     """
-    Event indicating that the order cancellation has been acknowledged by the broker and the order is no longer active at the execution venue.
+    Event indicating that the order cancellation has been acknowledged by the brokers and the order is no longer active at the execution venue.
 
     | Field                 | Type            | Semantics                                                                              |
     |-----------------------|-----------------|----------------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`           | Time at which the cancellation was observed by the system, as UTC epoch nanoseconds.   |
     | `ts_created_ns`       | `int`           | Time at which the event object was created, as UTC epoch nanoseconds.                  |
-    | `ts_broker_ns`        | `int`           | Time reported by the broker for the cancellation, as UTC epoch nanoseconds.            |
+    | `ts_broker_ns`        | `int`           | Time reported by the brokers for the cancellation, as UTC epoch nanoseconds.            |
     | `associated_order_id` | `uuid.UUID`     | Identifier of the cancelled order.                                                     |
     | `broker_order_id`     | `str` or `None` | Broker-assigned identifier of the cancelled order, if reported.                        |
     """
@@ -26,16 +26,16 @@ class CancellationAccepted(ResponseBase):
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class CancellationRejected(ResponseBase):
     """
-    Event indicating that the order cancellation has been rejected by the broker.
+    Event indicating that the order cancellation has been rejected by the brokers.
 
     | Field                 | Type                                 | Semantics                                                                          |
     |-----------------------|--------------------------------------|------------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`                                | Time at which the rejection was observed by the system, as UTC epoch nanoseconds.  |
     | `ts_created_ns`       | `int`                                | Time at which the event object was created, as UTC epoch nanoseconds.              |
-    | `ts_broker_ns`        | `int`                                | Time reported by the broker for the rejection, as UTC epoch nanoseconds.           |
+    | `ts_broker_ns`        | `int`                                | Time reported by the brokers for the rejection, as UTC epoch nanoseconds.           |
     | `associated_order_id` | `uuid.UUID`                          | Identifier of the order associated with the rejected cancellation.                 |
     | `rejection_reason`    | `models.CancellationRejectionReason` | Canonical classification of the cancellation rejection cause.                      |
-    | `rejection_message`   | `str`                                | Human-readable explanation provided by the broker.                                 |
+    | `rejection_message`   | `str`                                | Human-readable explanation provided by the brokers.                                 |
     """
 
     rejection_reason: models.CancellationRejectionReason

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/src/onesecondtrader/events/responses/modifications.py

@@ -10,13 +10,13 @@ from onesecondtrader.events.responses.base import ResponseBase
 class ModificationAccepted(ResponseBase):
     """
     Event indicating that the requested modification has been acknowledged by
-    the broker and that the updated order parameters are active at the execution venue.
+    the brokers and that the updated order parameters are active at the execution venue.
 
     | Field                 | Type            | Semantics                                                                              |
     |-----------------------|-----------------|----------------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`           | Time at which the acceptance was observed by the system, as UTC epoch nanoseconds.     |
     | `ts_created_ns`       | `int`           | Time at which the event object was created, as UTC epoch nanoseconds.                  |
-    | `ts_broker_ns`        | `int`           | Time reported by the broker for the modification acceptance, as UTC epoch nanoseconds. |
+    | `ts_broker_ns`        | `int`           | Time reported by the brokers for the modification acceptance, as UTC epoch nanoseconds. |
     | `associated_order_id` | `uuid.UUID`     | Identifier of the modified order.                                                      |
     | `broker_order_id`     | `str` or `None` | Broker-assigned identifier of the order after modification, if reported.               |
     """
@@ -27,16 +27,16 @@ class ModificationAccepted(ResponseBase):
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class ModificationRejected(ResponseBase):
     """
-    Event indicating that the requested modification has been rejected by the broker.
+    Event indicating that the requested modification has been rejected by the brokers.
 
     | Field                 | Type                                 | Semantics                                                                          |
     |-----------------------|--------------------------------------|------------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`                                | Time at which the rejection was observed by the system, as UTC epoch nanoseconds.  |
     | `ts_created_ns`       | `int`                                | Time at which the event object was created, as UTC epoch nanoseconds.              |
-    | `ts_broker_ns`        | `int`                                | Time reported by the broker for the rejection, as UTC epoch nanoseconds.           |
+    | `ts_broker_ns`        | `int`                                | Time reported by the brokers for the rejection, as UTC epoch nanoseconds.           |
     | `associated_order_id` | `uuid.UUID`                          | Identifier of the order associated with the rejected modification.                 |
     | `rejection_reason`    | `models.ModificationRejectionReason` | Canonical classification of the modification rejection cause.                      |
-    | `rejection_message`   | `str`                                | Human-readable explanation provided by the broker.                                 |
+    | `rejection_message`   | `str`                                | Human-readable explanation provided by the brokers.                                 |
     """
 
     rejection_reason: models.ModificationRejectionReason

{onesecondtrader-0.49.0 → onesecondtrader-0.51.0}/src/onesecondtrader/events/responses/orders.py

@@ -9,13 +9,13 @@ from onesecondtrader.events.responses.base import ResponseBase
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class OrderAccepted(ResponseBase):
     """
-    Event indicating that the order has been accepted by the broker and is active at the execution venue.
+    Event indicating that the order has been accepted by the brokers and is active at the execution venue.
 
     | Field                 | Type            | Semantics                                                                          |
     |-----------------------|-----------------|------------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`           | Time at which the acceptance was observed by the system, as UTC epoch nanoseconds. |
     | `ts_created_ns`       | `int`           | Time at which the event object was created, as UTC epoch nanoseconds.              |
-    | `ts_broker_ns`        | `int`           | Time reported by the broker for the acceptance, as UTC epoch nanoseconds.          |
+    | `ts_broker_ns`        | `int`           | Time reported by the brokers for the acceptance, as UTC epoch nanoseconds.          |
     | `associated_order_id` | `uuid.UUID`     | Identifier of the accepted order.                                                  |
     | `broker_order_id`     | `str` or `None` | Broker-assigned identifier of the accepted order.                                  |
     """
@@ -26,16 +26,16 @@ class OrderAccepted(ResponseBase):
 @dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
 class OrderRejected(ResponseBase):
     """
-    Event indicating that the order has been rejected by the broker.
+    Event indicating that the order has been rejected by the brokers.
 
     | Field                 | Type                          | Semantics                                                                          |
     |-----------------------|-------------------------------|------------------------------------------------------------------------------------|
     | `ts_event_ns`         | `int`                         | Time at which the rejection was observed by the system, as UTC epoch nanoseconds.  |
     | `ts_created_ns`       | `int`                         | Time at which the event object was created, as UTC epoch nanoseconds.              |
-    | `ts_broker_ns`        | `int`                         | Time reported by the broker for the rejection, as UTC epoch nanoseconds.           |
+    | `ts_broker_ns`        | `int`                         | Time reported by the brokers for the rejection, as UTC epoch nanoseconds.           |
     | `associated_order_id` | `uuid.UUID`                   | Identifier of the rejected order.                                                  |
     | `rejection_reason`    | `models.OrderRejectionReason` | Canonical classification of the rejection cause.                                   |
-    | `rejection_message`   | `str`                         | Human-readable explanation provided by the broker.                                 |
+    | `rejection_message`   | `str`                         | Human-readable explanation provided by the brokers.                                 |
     """
 
     rejection_reason: models.OrderRejectionReason

onesecondtrader-0.51.0/src/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-0.51.0/src/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-0.51.0/src/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 → onesecondtrader-0.51.0}/src/onesecondtrader/models/rejection_reasons.py

@@ -8,7 +8,7 @@ class OrderRejectionReason(enum.Enum):
     Enumeration of canonical order rejection reasons.
 
     This enumeration defines the system-level classification of order rejection causes.
-    It provides a stable, broker-agnostic taxonomy for programmatic handling of rejected orders.
+    It provides a stable, brokers-agnostic taxonomy for programmatic handling of rejected orders.
 
     | Value     | Semantics                                                                 |
     |-----------|---------------------------------------------------------------------------|
@@ -22,8 +22,8 @@ class ModificationRejectionReason(enum.Enum):
     """
     Enumeration of canonical order modification rejection reasons.
 
-    This enumeration defines the system-level classification of reasons for which an order modification request may be rejected by a broker.
-    It provides a stable, broker-agnostic taxonomy intended for programmatic handling and observability of modification rejections.
+    This enumeration defines the system-level classification of reasons for which an order modification request may be rejected by a brokers.
+    It provides a stable, brokers-agnostic taxonomy intended for programmatic handling and observability of modification rejections.
 
     | Value     | Semantics                                                                        |
     |-----------|----------------------------------------------------------------------------------|
@@ -37,8 +37,8 @@ class CancellationRejectionReason(enum.Enum):
     """
     Enumeration of canonical order cancellation rejection reasons.
 
-    This enumeration defines the system-level classification of reasons for which an order cancellation request may be rejected by a broker.
-    It provides a stable, broker-agnostic taxonomy intended for programmatic handling and observability of cancellation rejections.
+    This enumeration defines the system-level classification of reasons for which an order cancellation request may be rejected by a brokers.
+    It provides a stable, brokers-agnostic taxonomy intended for programmatic handling and observability of cancellation rejections.
 
     | Value     | Semantics                                                                        |
     |-----------|----------------------------------------------------------------------------------|