onesecondtrader 0.7.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

onesecondtrader/core/models.py

@@ -0,0 +1,133 @@
+from dataclasses import dataclass
+import enum
+
+
+class BrokerType(enum.Enum):
+    """
+    Enum for broker types.
+
+    **Attributes:**
+
+    | Enum | Value | Description |
+    |------|-------|-------------|
+    | `LOCAL_SIMULATED` | `enum.auto()` | Locally simulated broker |
+    | `IB_SIMULATED` | `enum.auto()` | Interactive Brokers paper trading account |
+    | `IB_LIVE` | `enum.auto()` | Interactive Brokers live trading account |
+    | `MT5` | `enum.auto()` | MetaTrader 5 |
+    """
+
+    LOCAL_SIMULATED = enum.auto()
+    IB_SIMULATED = enum.auto()
+    IB_LIVE = enum.auto()
+    MT5 = enum.auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Bar:
+    """
+    Class for representing a OHLC(V) bar of market data.
+
+    Attributes:
+        open (float): Open price
+        high (float): High price
+        low (float): Low price
+        close (float): Close price
+        volume (float): Volume
+    """
+
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float | None = None
+
+
+class Side(enum.Enum):
+    """
+    Enum for order sides.
+    """
+
+    BUY = enum.auto()
+    SELL = enum.auto()
+
+
+class TimeInForce(enum.Enum):
+    """
+    Order time-in-force specifications.
+
+    **Attributes:**
+
+    | Enum | Value | Description |
+    |------|-------|-------------|
+    | `DAY` | `enum.auto()` | Valid until end of trading day |
+    | `FOK` | `enum.auto()` | Fill entire order immediately or cancel (Fill-or-Kill) |
+    | `GTC` | `enum.auto()` | Active until explicitly cancelled (Good-Till-Cancelled) |
+    | `GTD` | `enum.auto()` | Active until specified date (Good-Till-Date) |
+    | `IOC` | `enum.auto()` | Execute available quantity immediately, cancel rest
+        (Immediate-or-Cancel) |
+    """
+
+    DAY = enum.auto()
+    FOK = enum.auto()
+    GTC = enum.auto()
+    GTD = enum.auto()
+    IOC = enum.auto()
+
+
+class OrderType(enum.Enum):
+    """
+    Enum for order types.
+
+    **Attributes:**
+
+    | Enum | Value | Description |
+    |------|-------|-------------|
+    | `MARKET` | `enum.auto()` | Market order |
+    | `LIMIT` | `enum.auto()` | Limit order |
+    | `STOP` | `enum.auto()` | Stop order |
+    | `STOP_LIMIT` | `enum.auto()` | Stop-limit order |
+    """
+
+    MARKET = enum.auto()
+    LIMIT = enum.auto()
+    STOP = enum.auto()
+    STOP_LIMIT = enum.auto()
+
+
+class OrderLifecycleState(enum.Enum):
+    """
+    Enum for order lifecycle states.
+
+    **Attributes:**
+
+    | Enum | Value | Description |
+    |------|-------|-------------|
+    | `PENDING` | `enum.auto()` | Order has been submitted, but not yet acknowledged by
+        the broker |
+    | `OPEN` | `enum.auto()` | Order has been acknowledged by the broker, but not yet
+        filled or cancelled |
+    | `FILLED` | `enum.auto()` | Order has been filled |
+    | `CANCELLED` | `enum.auto()` | Order has been cancelled |
+    """
+
+    PENDING = enum.auto()
+    OPEN = enum.auto()
+    PARTIALLY_FILLED = enum.auto()
+    FILLED = enum.auto()
+    CANCELLED = enum.auto()
+
+
+class OrderRejectionReason(enum.Enum):
+    """
+    Enum for order rejection reasons.
+
+    **Attributes:**
+
+    | Enum | Value | Description |
+    |------|-------|-------------|
+    | `UNKNOWN` | `enum.auto()` | Unknown reason |
+    | `NEGATIVE_QUANTITY` | `enum.auto()` | Negative quantity |
+    """
+
+    UNKNOWN = enum.auto()
+    NEGATIVE_QUANTITY = enum.auto()

onesecondtrader/messaging/eventbus.py

@@ -0,0 +1,490 @@
+"""
+This module provides the event bus for managing event-driven communication between
+ the trading infrastructure's components via a publish-subscribe messaging pattern.
+"""
+
+import collections
+import inspect
+import logging
+import threading
+from collections.abc import Callable
+from onesecondtrader.messaging import events
+from onesecondtrader.monitoring import console
+
+
+class EventBus:
+    # noinspection PyTypeChecker
+    """
+    Event bus for managing event-driven communication between the trading
+     infrastructure's components via a publish-subscribe messaging pattern.
+    Supports inheritance-based subscriptions where handlers subscribed to a parent event
+     type will receive events of child types.
+    Each subscription can include an optional filter function to receive only specific
+     events of a given type (e.g. filtering `IncomingBar` events for a specific symbol).
+
+    Examples:
+        >>> # Import necessary modules
+        >>> import pandas as pd
+        >>> from onesecondtrader.messaging.eventbus import EventBus
+        >>> from onesecondtrader.messaging import events
+        >>> from onesecondtrader.core import models
+
+        >>> # Instantiate event bus
+        >>> event_bus = EventBus()
+
+        >>> # Create a dummy handler that simply prints the symbol of the received event
+        >>> def dummy_handler(incoming_bar_event: events.Market.IncomingBar):
+        ...     print(f"Received: {incoming_bar_event.symbol}")
+
+        >>> # Subscribe to IncomingBar events whose symbol is AAPL
+        >>> event_bus.subscribe(
+        ...     events.Market.IncomingBar,
+        ...     dummy_handler,
+        ...     lambda event: event.symbol == "AAPL" # Lambda filter function
+        ... )
+
+        >>> # Create events to publish
+        >>> aapl_event = events.Market.IncomingBar(
+        ...     ts_event=pd.Timestamp("2023-01-01", tz="UTC"),
+        ...     symbol="AAPL",
+        ...     bar=models.Bar(
+        ...         open=100.0, high=101.0, low=99.0,
+        ...         close=100.5, volume=1000
+        ...     )
+        ... )
+        >>> googl_event = events.Market.IncomingBar(
+        ...     ts_event=pd.Timestamp("2023-01-01", tz="UTC"),
+        ...     symbol="GOOGL",
+        ...     bar=models.Bar(
+        ...         open=2800.0, high=2801.0, low=2799.0,
+        ...         close=2800.5, volume=500
+        ...     )
+        ... )
+
+        >>> # Publish events - only AAPL passes filter and will be printed
+        >>> event_bus.publish(aapl_event)
+        Received: AAPL
+        >>> event_bus.publish(googl_event)
+
+        >>> # Unsubscribe the dummy handler
+        >>> event_bus.unsubscribe(events.Market.IncomingBar, dummy_handler)
+
+        >>> # Publish again - no handler receives it (warning will be logged)
+        >>> event_bus.publish(aapl_event)  # doctest: +SKIP
+        WARNING:root:Published IncomingBar but no subscribers exist - check event wiring
+    """
+
+    def __init__(self) -> None:
+        """
+        Initializes the event bus with optimized data structures for high-performance
+        event publishing.
+
+        Attributes:
+            self._handlers (collections.defaultdict): Direct storage mapping event types
+                 to handler lists
+            self._publish_cache (dict): Pre-computed cache for O(1) publish operations
+            self._lock (threading.Lock): Single lock for all operations
+                (subscribe/unsubscribe are rare)
+            self._sequence_number (int): Sequence number counter for events
+        """
+        self._handlers: dict[
+            type[events.Base.Event],
+            list[
+                tuple[
+                    Callable[[events.Base.Event], None],
+                    Callable[[events.Base.Event], bool],
+                ]
+            ],
+        ] = collections.defaultdict(list)
+
+        self._publish_cache: dict[
+            type[events.Base.Event],
+            list[
+                tuple[
+                    Callable[[events.Base.Event], None],
+                    Callable[[events.Base.Event], bool],
+                ]
+            ],
+        ] = {}
+
+        self._lock: threading.Lock = threading.Lock()
+        self._sequence_number: int = -1
+
+        self._rebuild_cache()
+
+    def subscribe(
+        self,
+        event_type: type[events.Base.Event],
+        event_handler: Callable[[events.Base.Event], None],
+        event_filter: Callable[[events.Base.Event], bool] | None = None,
+    ) -> None:
+        """
+        The `subscribe` method registers an event handler for event messages of a
+         specified type and all its subtypes (expressed as subclasses in the event
+          dataclass hierarchy, so-called inheritance-based subscription).
+        When an event of that type or any subtype is published, the handler will be
+         invoked if the associated `event_filter` returns `True` for that event
+         instance.
+        A given handler can only be subscribed once per event type.
+        If the handler is already subscribed to the given event type
+         —regardless of the filter function—
+        the subscription attempt is ignored and a warning is logged.
+
+        Arguments:
+            event_type (type[events.Base.Event]): Type of the event to subscribe to,
+             must be a subclass of `events.Base.Event`.
+            event_handler (Callable[events.Base.Event, None]): Function to call when an
+                 event of the given type is published.
+                This callable must accept a single argument of type `events.Base.Event`
+                 (or its subclass).
+            event_filter (Callable[[events.Base.Event], bool] | None): Function to
+                 determine whether to call the event handler for a given event.
+                Should accept one event and return `True` to handle or `False` to
+                 ignore.
+                Defaults to `None`, which creates a filter that always returns `True`
+                 (i.e. always call the event handler).
+        """
+
+        if not issubclass(event_type, events.Base.Event):
+            console.logger.error(
+                f"Invalid subscription attempt: event_type must be a subclass of "
+                f"Event, got {type(event_type).__name__}"
+            )
+            return
+
+        if not callable(event_handler):
+            console.logger.error(
+                f"Invalid subscription attempt: event_handler must be callable, "
+                f"got {type(event_handler).__name__}"
+            )
+            return
+
+        if event_filter is None:
+
+            def event_filter(event: events.Base.Event) -> bool:
+                return True
+
+        if not callable(event_filter):
+            console.logger.error(
+                f"Invalid subscription attempt: event_filter must be callable, "
+                f"got {type(event_filter).__name__}"
+            )
+            return
+
+        is_valid, error_msg = self._validate_filter_signature(event_filter)
+        if not is_valid:
+            console.logger.error(f"Invalid subscription attempt: {error_msg}")
+            return
+
+        with self._lock:
+            if any(
+                event_handler == existing_handler
+                for existing_handler, _ in self._handlers[event_type]
+            ):
+                console.logger.warning(
+                    f"Duplicate subscription attempt: event_handler was already "
+                    f"subscribed to {event_type.__name__}"
+                )
+                return
+
+            self._handlers[event_type].append((event_handler, event_filter))
+
+            self._rebuild_cache()
+
+            handler_name = getattr(event_handler, "__name__", "<lambda>")
+            console.logger.info(f"Subscribed {handler_name} to {event_type.__name__}.")
+
+    def unsubscribe(
+        self,
+        event_type: type[events.Base.Event],
+        event_handler: Callable[[events.Base.Event], None],
+    ) -> None:
+        """
+        The `unsubscribe` method removes an event handler from the subscribers list for
+         the specified event type.
+        If the event handler is not subscribed to the given event type, the
+         unsubscription attempt is ignored and a warning is logged.
+        After removing the event handler, the event type may have an empty subscribers
+         list but remains in the `subscribers` dictionary.
+
+        Arguments:
+            event_type (type[events.Base.Event]): Type of the event to unsubscribe from,
+                 must be a subclass of `events.Base.Event`.
+            event_handler (Callable[events.Base.Event, None]): Event handler to remove
+                 from the subscribers list (this will also remove the associated filter
+                 function).
+        """
+        if not issubclass(event_type, events.Base.Event):
+            console.logger.error(
+                f"Invalid unsubscription attempt: event_type must be a subclass of "
+                f"Event, got {type(event_type).__name__}"
+            )
+            return
+
+        if not callable(event_handler):
+            console.logger.error(
+                f"Invalid unsubscription attempt: callback must be callable, "
+                f"got {type(event_handler).__name__}"
+            )
+            return
+
+        with self._lock:
+            if event_type not in self._handlers:
+                console.logger.warning(
+                    f"Attempted to unsubscribe from {event_type.__name__}, "
+                    f"but no subscribers exist"
+                )
+                return
+
+            current_handlers = self._handlers[event_type]
+            new_handlers = [
+                (existing_handler, existing_filter)
+                for existing_handler, existing_filter in current_handlers
+                if existing_handler != event_handler
+            ]
+
+            removed_count = len(current_handlers) - len(new_handlers)
+            if removed_count == 0:
+                handler_name = getattr(event_handler, "__name__", "<lambda>")
+                console.logger.warning(
+                    f"Attempted to unsubscribe {handler_name} from "
+                    f"{event_type.__name__}, but it was not subscribed"
+                )
+                return
+
+            if new_handlers:
+                self._handlers[event_type] = new_handlers
+            else:
+                # Clean up empty lists
+                del self._handlers[event_type]
+
+            self._rebuild_cache()
+
+            handler_name = getattr(event_handler, "__name__", "<lambda>")
+            console.logger.info(
+                f"Unsubscribed {handler_name} from "
+                f"{event_type.__name__} (removed {removed_count} subscription(s))"
+            )
+
+    def publish(self, event: events.Base.Event) -> None:
+        """
+        The `publish` method delivers the event to all handlers subscribed to the
+         event's type or any of its parent types (inheritance-based subscription).
+        Handlers are only called if their filter function returns True for this event.
+        Handlers are called synchronously in the order they were subscribed.
+
+        This method uses a pre-computed handler cache for O(1) lookup performance
+        and runs without locks for maximum concurrency.
+
+        Arguments:
+            event (events.Base.Event): Event to publish. Must be an instance of
+                 `events.Base.Event` or one of its subclasses.
+        """
+        if not isinstance(event, events.Base.Event):
+            console.logger.error(
+                f"Invalid publish attempt: event must be an instance of Event, "
+                f"got {type(event).__name__}"
+            )
+            return
+
+        object.__setattr__(
+            event, "event_bus_sequence_number", self._set_sequence_number()
+        )
+
+        event_type: type[events.Base.Event] = type(event)
+
+        handlers = self._publish_cache.get(event_type, [])
+
+        if not handlers:
+            console.logger.warning(
+                f"Published {event_type.__name__} but no subscribers exist - "
+                f"check event wiring"
+            )
+            return
+
+        delivered_count = 0
+        for event_handler, event_filter in handlers:
+            try:
+                should_handle = event_filter(event)
+
+                if not isinstance(should_handle, bool):
+                    handler_name = getattr(event_handler, "__name__", "<lambda>")
+                    console.logger.warning(
+                        f"Filter for handler {handler_name} returned "
+                        f"{type(should_handle).__name__}, expected bool. "
+                        f"Treating as False."
+                    )
+                    should_handle = False
+
+            except TypeError as type_error:
+                handler_name = getattr(event_handler, "__name__", "<lambda>")
+                if "takes" in str(type_error) and "positional argument" in str(
+                    type_error
+                ):
+                    console.logger.error(
+                        f"Filter for handler {handler_name} has wrong signature: "
+                        f"{type_error}"
+                    )
+                else:
+                    console.logger.exception(
+                        f"Filter function for handler {handler_name} failed "
+                        f"processing {event_type.__name__}: {type_error}"
+                    )
+                continue
+            except Exception as filter_exception:
+                handler_name = getattr(event_handler, "__name__", "<lambda>")
+                console.logger.exception(
+                    f"Filter function for handler {handler_name} failed "
+                    f"processing {event_type.__name__}: {filter_exception}"
+                )
+                continue
+
+            if should_handle:
+                try:
+                    event_handler(event)
+                    delivered_count += 1
+                except Exception as handler_exception:
+                    handler_name = getattr(event_handler, "__name__", "<lambda>")
+                    console.logger.exception(
+                        f"Handler {handler_name} failed processing "
+                        f"{event_type.__name__}: {handler_exception}"
+                    )
+
+        if delivered_count == 0:
+            console.logger.warning(
+                f"Published {event_type.__name__} but no handlers received it - "
+                f"all {len(handlers)} handler(s) filtered out the event"
+            )
+        else:
+            # Conditional debug logging to avoid string formatting overhead
+            if console.logger.isEnabledFor(logging.DEBUG):
+                console.logger.debug(
+                    f"Published {event_type.__name__} to {delivered_count} handler(s)"
+                )
+
+    @staticmethod
+    def _validate_filter_signature(
+        event_filter: Callable[[events.Base.Event], bool],
+    ) -> tuple[bool, str | None]:
+        """
+        Validate that filter function has the correct signature.
+
+        A valid filter function must:
+        - Accept exactly 1 parameter (the event)
+        - Not use *args or **kwargs
+        - Optionally return bool (if type annotated)
+
+        Arguments:
+            event_filter (Callable): The filter function to validate
+
+        Returns:
+            tuple[bool, str | None]: (is_valid, error_message)
+                is_valid: True if signature is valid, False otherwise
+                error_message: Description of the issue if invalid, None if valid
+        """
+        try:
+            sig = inspect.signature(event_filter)
+            params = list(sig.parameters.values())
+
+            if len(params) != 1:
+                return (
+                    False,
+                    f"Filter must accept exactly 1 parameter, got {len(params)}",
+                )
+
+            param = params[0]
+            if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                return (
+                    False,
+                    "Filter cannot use *args - must accept exactly 1 event parameter",
+                )
+            if param.kind == inspect.Parameter.VAR_KEYWORD:
+                return (
+                    False,
+                    "Filter cannot use **kwargs - must accept exactly 1 event "
+                    "parameter",
+                )
+
+            if sig.return_annotation is not inspect.Parameter.empty:
+                if sig.return_annotation is not bool:
+                    return (
+                        False,
+                        f"Filter return type should be bool, got "
+                        f"{sig.return_annotation}",
+                    )
+
+            return True, None
+
+        except Exception as e:
+            return False, f"Could not inspect filter signature: {e}"
+
+    def _set_sequence_number(self) -> int:
+        """
+        Increment and return the event bus sequence number in a thread-safe manner.
+        """
+        with self._lock:
+            self._sequence_number += 1
+            return self._sequence_number
+
+    @staticmethod
+    def _get_all_concrete_event_types() -> list[type[events.Base.Event]]:
+        """
+        Dynamically discover all concrete event types from the events module.
+        Automatically adapts to namespace changes without code modifications.
+
+        Returns:
+            list[type[events.Base.Event]]: List of concrete event classes that can be
+                instantiated and published.
+        """
+        concrete_types = []
+
+        for attr_name in dir(events):
+            if attr_name.startswith("_"):
+                continue
+
+            attr = getattr(events, attr_name)
+
+            if not inspect.isclass(attr) or attr_name == "Base":
+                continue
+
+            for member_name, member_obj in inspect.getmembers(attr, inspect.isclass):
+                if (
+                    issubclass(member_obj, events.Base.Event)
+                    and member_obj != events.Base.Event
+                    and not inspect.isabstract(member_obj)
+                ):
+                    concrete_types.append(member_obj)
+
+        return concrete_types
+
+    def _rebuild_cache(self) -> None:
+        """
+        Rebuild the pre-computed publish cache for all concrete event types.
+        This method should be called whenever subscriptions change.
+        """
+        new_cache = {}
+        concrete_event_types = self._get_all_concrete_event_types()
+
+        for concrete_event_type in concrete_event_types:
+            handlers = []
+            seen_handler_ids = set()
+
+            for handler_type, handler_list in self._handlers.items():
+                if issubclass(concrete_event_type, handler_type):
+                    for handler, filter_func in handler_list:
+                        handler_id = id(handler)
+                        if handler_id not in seen_handler_ids:
+                            handlers.append((handler, filter_func))
+                            seen_handler_ids.add(handler_id)
+
+            if handlers:
+                new_cache[concrete_event_type] = handlers
+
+        self._publish_cache = new_cache
+
+        if console.logger.isEnabledFor(logging.DEBUG):
+            console.logger.debug(
+                f"Publish cache rebuilt: {len(new_cache)} event types cached, "
+                f"total handlers: "
+                f"{sum(len(handlers) for handlers in new_cache.values())}"
+            )