onesecondtrader 0.7.0__py3-none-any.whl → 0.8.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/events.py

@@ -0,0 +1,742 @@
+"""
+This module provides the event messages used for decoupled communication between the
+ trading infrastructure's components.
+Events are organized into namespaces (`Market`, `Request`, `Response`, and `System`)
+ to provide clear semantic groupings.
+Base event messages used for structure inheritance are grouped under the
+ `Base` namespace.
+Dataclass field validation logic is grouped under the `_Validate` namespace.
+
+???+ note "Module Overview: `events.py`"
+    ```mermaid
+    ---
+    config:
+      themeVariables:
+        fontSize: "11px"
+    ---
+    graph LR
+
+    R[events.Base.Event]
+    R1[events.Base.Market]
+    R2[events.Base.Request]
+    R21[events.Base.OrderRequest]
+    R22[events.Base.CancelRequest]
+    R3[events.Base.Response]
+    R4[events.Base.System]
+
+    R --> R1
+    R --> R2
+    R --> R3
+    R --> R4
+
+    R2 --> R21
+    R2 --> R22
+
+    A1[events.Market.IncomingBar]
+
+    R1 --> A1
+
+    style A1 fill:#6F42C1,fill-opacity:0.3
+
+    B1[events.Request.MarketOrder]
+    B2[events.Request.LimitOrder]
+    B3[events.Request.StopOrder]
+    B4[events.Request.StopLimitOrder]
+    B5[events.Request.CancelOrder]
+    B6[events.Request.FlushSymbol]
+    B7[events.Request.FlushAll]
+
+    R21 --> B1
+    R21 --> B2
+    R21 --> B3
+    R21 --> B4
+    R22 --> B5
+    R22 --> B6
+    R22 --> B7
+
+    style B1 fill:#6F42C1,fill-opacity:0.3
+    style B2 fill:#6F42C1,fill-opacity:0.3
+    style B3 fill:#6F42C1,fill-opacity:0.3
+    style B4 fill:#6F42C1,fill-opacity:0.3
+    style B5 fill:#6F42C1,fill-opacity:0.3
+    style B6 fill:#6F42C1,fill-opacity:0.3
+    style B7 fill:#6F42C1,fill-opacity:0.3
+
+    C1[events.Response.OrderSubmitted]
+    C2[events.Response.OrderFilled]
+    C3[events.Response.OrderCancelled]
+    C4[events.Response.OrderRejected]
+
+    R3 --> C1
+    R3 --> C2
+    R3 --> C3
+    R3 --> C4
+
+    style C1 fill:#6F42C1,fill-opacity:0.3
+    style C2 fill:#6F42C1,fill-opacity:0.3
+    style C3 fill:#6F42C1,fill-opacity:0.3
+    style C4 fill:#6F42C1,fill-opacity:0.3
+
+    D1[events.System.Shutdown]
+
+    R4 --> D1
+
+    style D1 fill:#6F42C1,fill-opacity:0.3
+
+
+    subgraph Market ["Market Update Event Messages"]
+        R1
+        A1
+
+        subgraph MarketNamespace ["events.Market Namespace"]
+            A1
+        end
+
+    end
+
+
+    subgraph Request ["Broker Request Event Messages"]
+        R2
+        R21
+        R22
+        B1
+        B2
+        B3
+        B4
+        B5
+        B6
+        B7
+
+        subgraph RequestNamespace ["events.Request Namespace"]
+            B1
+            B2
+            B3
+            B4
+            B5
+            B6
+            B7
+        end
+
+    end
+
+    subgraph Response ["Broker Response Event Messages"]
+        R3
+        C1
+        C2
+        C3
+        C4
+
+        subgraph ResponseNamespace ["events.Response Namespace"]
+            C1
+            C2
+            C3
+            C4
+        end
+
+    end
+
+    subgraph System ["System-Internal Event Messages"]
+        R4
+        D1
+
+        subgraph SystemNamespace ["events.System Namespace"]
+            D1
+        end
+
+    end
+    ```
+"""
+
+import dataclasses
+import pandas as pd
+import re
+import uuid
+from onesecondtrader.core import models
+from onesecondtrader.monitoring import console
+
+
+class Base:
+    """
+    Namespace for event base dataclasses.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Event:
+        """
+        Base event message dataclass.
+        This dataclass cannot be instantiated directly.
+
+        Attributes:
+            ts_event (pd.Timestamp): Timestamp of the event in pandas Timestamp format.
+                (Must be timezone-aware.)
+            event_bus_sequence_number (int | None): Auto-generated Sequence number of
+                 the event.
+                This will be assigned as soon as the event enters the event bus via
+                 `messaging.EventBus.publish(<event>)`.
+        """
+
+        ts_event: pd.Timestamp
+        event_bus_sequence_number: int | None = dataclasses.field(
+            default=None, init=False
+        )
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.Event:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+        def __post_init__(self) -> None:
+            _Validate.timezone_aware(self.ts_event, "ts_event", "Event")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Market(Event):
+        """
+        Base event message dataclass for market events.
+        Inherits from `Base.Event`.
+        Each market event message is associated with a specific financial instrument via
+         the `symbol` field.
+        This dataclass cannot be instantiated directly.
+
+        Attributes:
+            symbol (str): Symbol of the financial instrument.
+        """
+
+        symbol: str
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.Market:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+        def __post_init__(self) -> None:
+            super().__post_init__()
+            _Validate.symbol(self.symbol, "Market event")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Request(Event):
+        """
+        Base event message dataclass for broker requests.
+        This dataclass cannot be instantiated directly.
+        `ts_event` is auto-generated by default.
+
+        Attributes:
+            ts_event: Timestamp of the event. (defaults to current UTC time;
+                auto-generated)
+        """
+
+        ts_event: pd.Timestamp = dataclasses.field(
+            default_factory=lambda: pd.Timestamp.now(tz="UTC")
+        )
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.Request:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderRequest(Request):
+        """
+        Base event message dataclass for order requests.
+        Inherits from `Base.Request`.
+        This dataclass cannot be instantiated directly.
+
+        Attributes:
+            symbol (str): Symbol of the financial instrument.
+            side (models.Side): Side of the order.
+            quantity (float): Quantity of the order.
+            time_in_force (models.TimeInForce): Time in force of the order.
+            order_expiration (pd.Timestamp | None): Expiration timestamp of the order
+                (optional).
+                Only relevant if `time_in_force` is `models.TimeInForce.GTD`.
+            order_id (uuid.UUID): Unique ID of the order. (auto-generated)
+        """
+
+        symbol: str
+        side: models.Side
+        quantity: float
+        time_in_force: models.TimeInForce
+        order_expiration: pd.Timestamp | None = None
+        order_id: uuid.UUID = dataclasses.field(default_factory=uuid.uuid4)
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.OrderRequest:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+        def __post_init__(self) -> None:
+            super().__post_init__()
+            _Validate.symbol(self.symbol, f"Order {self.order_id}")
+
+            _Validate.timezone_aware(
+                self.order_expiration, "order_expiration", f"Order {self.order_id}"
+            )
+            _Validate.quantity(self.quantity, f"Order {self.order_id}")
+
+            if self.time_in_force.value == 4:
+                if self.order_expiration is None:
+                    console.logger.error(
+                        f"Order {self.order_id}: GTD order missing expiration "
+                        f"timestamp."
+                    )
+                elif self.order_expiration <= self.ts_event:
+                    console.logger.error(
+                        f"Order {self.order_id}: GTD expiration "
+                        f"{self.order_expiration} "
+                        f"is not after event timestamp {self.ts_event}."
+                    )
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class CancelRequest(Request):
+        """
+        Base event message dataclass for order cancellation requests.
+        Inherits from `Base.Request`.
+        This dataclass cannot be instantiated directly.
+        """
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.CancelRequest:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Response(Event):
+        """
+        Base event message dataclass for broker responses.
+        This dataclass cannot be instantiated directly.
+        """
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.Response:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class System(Event):
+        """
+        Base event message dataclass for system-internal messages.
+        This dataclass cannot be instantiated directly.
+        `ts_event` is auto-generated by default.
+
+        Attributes:
+            ts_event: Timestamp of the event. (defaults to current UTC time;
+                auto-generated)
+        """
+
+        ts_event: pd.Timestamp = dataclasses.field(
+            default_factory=lambda: pd.Timestamp.now(tz="UTC")
+        )
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.System:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+
+class Market:
+    """
+    Namespace for market update event messages.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class IncomingBar(Base.Market):
+        """
+        Event message dataclass for incoming market data bars.
+        Inherits from `Base.Market`.
+
+        Attributes:
+            bar (models.Bar): Bar of market data.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> from onesecondtrader.core import models
+            >>> event = events.Market.IncomingBar(
+            ...     ts_event=pd.Timestamp("2023-01-01 00:00:00", tz="UTC"),
+            ...     symbol="AAPL",
+            ...     bar=models.Bar(
+            ...         open=100.0,
+            ...         high=101.0,
+            ...         low=99.0,
+            ...         close=100.5,
+            ...         volume=10000,
+            ...     ),
+            ... )
+            ```
+        """
+
+        bar: models.Bar
+
+
+class Request:
+    """
+    Namespace for broker request event messages.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class MarketOrder(Base.OrderRequest):
+        """
+        Event message dataclass for submitting a market order to the broker.
+
+        Attributes:
+            order_type (models.OrderType): Type of the order (automatically set to
+            models.OrderType.MARKET).
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.MarketOrder(
+            ...     symbol="AAPL",
+            ...     side=models.Side.BUY,
+            ...     quantity=100.0,
+            ...     time_in_force=models.TimeInForce.DAY,
+            ... )
+        """
+
+        order_type: models.OrderType = dataclasses.field(
+            init=False, default=models.OrderType.MARKET
+        )
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class LimitOrder(Base.OrderRequest):
+        """
+        Event message dataclass for submitting a limit order to the broker.
+
+        Attributes:
+            order_type (models.OrderType): Type of the order (automatically set to
+            models.OrderType.LIMIT).
+            limit_price (float): Limit price of the order.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.LimitOrder(
+            ...     symbol="AAPL",
+            ...     side=models.Side.BUY,
+            ...     quantity=100.0,
+            ...     time_in_force=models.TimeInForce.DAY,
+            ...     limit_price=100.0,
+            ... )
+        """
+
+        order_type: models.OrderType = dataclasses.field(
+            init=False, default=models.OrderType.LIMIT
+        )
+        limit_price: float
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class StopOrder(Base.OrderRequest):
+        """
+        Event message dataclass for submitting a stop order to the broker.
+
+        Attributes:
+            order_type (models.OrderType): Type of the order (automatically set to
+            models.OrderType.STOP).
+            stop_price (float): Stop price of the order.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.StopOrder(
+            ...     symbol="AAPL",
+            ...     side=models.Side.BUY,
+            ...     quantity=100.0,
+            ...     time_in_force=models.TimeInForce.DAY,
+            ...     stop_price=100.0,
+            ... )
+        """
+
+        order_type: models.OrderType = dataclasses.field(
+            init=False, default=models.OrderType.STOP
+        )
+        stop_price: float
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class StopLimitOrder(Base.OrderRequest):
+        """
+        Event message dataclass for submitting a stop-limit order to the broker.
+
+        Attributes:
+            order_type (models.OrderType): Type of the order (automatically set to
+            models.OrderType.STOP_LIMIT).
+            stop_price (float): Stop price of the order.
+            limit_price (float): Limit price of the order.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.StopLimitOrder(
+            ...     symbol="AAPL",
+            ...     side=models.Side.BUY,
+            ...     quantity=100.0,
+            ...     time_in_force=models.TimeInForce.DAY,
+            ...     stop_price=100.0,
+            ...     limit_price=100.0,
+            ... )
+        """
+
+        order_type: models.OrderType = dataclasses.field(
+            init=False, default=models.OrderType.STOP_LIMIT
+        )
+        stop_price: float
+        limit_price: float
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class CancelOrder(Base.CancelRequest):
+        """
+        Event message dataclass for cancelling an order.
+
+        Attributes:
+            order_id (uuid.UUID): Unique ID of the order to cancel.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.CancelOrder(
+            ...     order_id=uuid.UUID("12345678-1234-5678-1234-567812345678"),
+            ... )
+        """
+
+        order_id: uuid.UUID
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class FlushSymbol(Base.Request):
+        """
+        Event message dataclass for flushing all orders for a symbol.
+
+        Attributes:
+            symbol (str): Symbol to flush.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.FlushSymbol(
+            ...     symbol="AAPL",
+            ... )
+        """
+
+        symbol: str
+
+        def __post_init__(self) -> None:
+            super().__post_init__()
+            _Validate.symbol(self.symbol, "Flush request")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class FlushAll(Base.Request):
+        """
+        Event message dataclass for flushing all orders for all symbols.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.FlushAll()
+        """
+
+        pass
+
+
+class Response:
+    """
+    Namespace for broker response event messages.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderSubmitted(Base.Response):
+        """
+        Event message dataclass for order submission confirmation from the broker.
+
+        Attributes:
+            order_submitted_id (uuid.UUID): Unique ID of the submitted order.
+            associated_request_id (uuid.UUID): Unique ID of the request that triggered
+                the order submission.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> import pandas as pd
+            >>> import uuid
+            >>> event = events.Response.OrderSubmitted(
+            ...     ts_event=pd.Timestamp(
+            ...         "2023-01-01 00:00:00", tz="UTC"),
+            ...     order_submitted_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"),
+            ...     associated_request_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"
+            ...     ),
+            ... )
+        """
+
+        order_submitted_id: uuid.UUID
+        associated_request_id: uuid.UUID
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderFilled(Base.Response):
+        """
+        Event message dataclass for order fill confirmation from the broker.
+
+        Attributes:
+            fill_id (uuid.UUID): Unique ID of the fill. (auto-generated)
+            associated_order_submitted_id (uuid.UUID): Unique ID of the submitted order
+                that triggered the fill.
+            side (models.Side): Side of the fill.
+            quantity_filled (float): Quantity filled.
+            filled_at_price (float): Price at which the fill was executed.
+            commission_and_fees (float): Commission and fees for the fill.
+            net_fill_value (float): Net fill value (auto-generated).
+            exchange (str | None): Exchange on which the fill was executed. (optional;
+                defaults to "SIMULATED")
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> from onesecondtrader.core import models
+            >>> import pandas as pd
+            >>> import uuid
+            >>> event = events.Response.OrderFilled(
+            ...     ts_event=pd.Timestamp("2023-01-01 00:00:00", tz="UTC"),
+            ...     associated_order_submitted_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"
+            ...     ),
+            ...     side=models.Side.BUY,
+            ...     quantity_filled=100.0,
+            ...     filled_at_price=100.0,
+            ...     commission_and_fees=1.0,
+            ... )
+        """
+
+        fill_id: uuid.UUID = dataclasses.field(default_factory=uuid.uuid4)
+        associated_order_submitted_id: uuid.UUID
+        side: models.Side
+        quantity_filled: float
+        filled_at_price: float
+        commission_and_fees: float
+        net_fill_value: float = dataclasses.field(init=False)
+        exchange: str | None = None
+
+        def __post_init__(self):
+            object.__setattr__(self, "fill_id", self.fill_id or uuid.uuid4())
+
+            gross_value = self.filled_at_price * self.quantity_filled
+
+            if self.side.value == 1:
+                net_value = gross_value + self.commission_and_fees
+            else:
+                net_value = gross_value - self.commission_and_fees
+
+            object.__setattr__(self, "net_fill_value", net_value)
+
+            object.__setattr__(self, "exchange", self.exchange or "SIMULATED")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderCancelled(Base.Response):
+        """
+        Event message dataclass for order cancellation confirmation from the broker.
+
+        Attributes:
+            associated_order_submitted_id (uuid.UUID): Unique ID of the submitted order
+                that was cancelled.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> import pandas as pd
+            >>> import uuid
+            >>> event = events.Response.OrderCancelled(
+            ...     ts_event=pd.Timestamp("2023-01-01 00:00:00", tz="UTC"),
+            ...     associated_order_submitted_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"
+            ...     ),
+            ... )
+        """
+
+        associated_order_submitted_id: uuid.UUID
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderRejected(Base.Response):
+        """
+        Event message dataclass for order rejection confirmation from the broker.
+
+        Attributes:
+            associated_order_submitted_id (uuid.UUID): Unique ID of the submitted order
+                that was rejected.
+            reason (models.OrderRejectionReason): Reason for the rejection.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> from onesecondtrader.core import models
+            >>> import pandas as pd
+            >>> import uuid
+            >>> event = events.Response.OrderRejected(
+            ...     ts_event=pd.Timestamp("2023-01-01 00:00:00", tz="UTC"),
+            ...     associated_order_submitted_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"
+            ...     ),
+            ...     reason=models.OrderRejectionReason.NEGATIVE_QUANTITY,
+            ... )
+        """
+
+        associated_order_submitted_id: uuid.UUID
+        reason: models.OrderRejectionReason
+
+
+class System:
+    """
+    Namespace for system-internal event messages.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Shutdown(Base.System):
+        """
+        Event message dataclass for system shutdown.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.System.Shutdown()
+        """
+
+        pass
+
+
+class _Validate:
+    """Internal validation utilities for events."""
+
+    @staticmethod
+    def symbol(symbol: str, context: str = "") -> None:
+        """Validate symbol format and log errors."""
+        if not symbol or not symbol.strip():
+            console.logger.error(f"{context}: Symbol cannot be empty or whitespace")
+            return
+
+        if not re.fullmatch(r"[A-Z0-9._-]+", symbol):
+            console.logger.error(f"{context}: Invalid symbol format: {symbol}")
+
+    @staticmethod
+    def quantity(quantity: float, context: str = "") -> None:
+        """Validate quantity values and log errors."""
+        if (
+            quantity != quantity
+            or quantity == float("inf")
+            or quantity == float("-inf")
+        ):
+            console.logger.error(f"{context}: quantity cannot be NaN or infinite")
+            return
+
+        if quantity <= 0:
+            console.logger.error(
+                f"{context}: quantity must be positive, got {quantity}"
+            )
+
+        if quantity > 1e9:
+            console.logger.error(f"{context}: quantity too large: {quantity}")
+
+    @staticmethod
+    def timezone_aware(
+        timestamp: pd.Timestamp | None, field_name: str, context: str = ""
+    ) -> None:
+        """Validate that timestamp is timezone-aware and log errors."""
+        if timestamp is not None and timestamp.tz is None:
+            console.logger.error(
+                f"{context}: {field_name} must be timezone-aware, got {timestamp}"
+            )

onesecondtrader/monitoring/console.py

@@ -5,6 +5,7 @@ Simple console logging configuration for terminal output.
 
 import logging
 
+
 logging.basicConfig(
     level=logging.DEBUG,
     format="%(asctime)s - %(levelname)s - %(threadName)s - %(message)s",

{onesecondtrader-0.7.0.dist-info → onesecondtrader-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: onesecondtrader
-Version: 0.7.0
+Version: 0.8.0
 Summary: The Trading Infrastructure Toolkit for Python. Research, simulate, and deploy algorithmic trading strategies — all in one place.
 Author: Nils P. Kujath
 Author-email: 63961429+NilsKujath@users.noreply.github.com

onesecondtrader-0.8.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+onesecondtrader/__init__.py,sha256=TNqlT20sH46-J7F6giBxwWYG1-wFZZt7toDbZeQK6KQ,210
+onesecondtrader/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/core/models.py,sha256=Pw3og5b2mzcoPpMfv3ZdKPvUvhLvh_eT68WJSlIpRyo,3325
+onesecondtrader/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/messaging/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/messaging/events.py,sha256=eaWXQQIUnRNOR-9n5-6lyLbZ6bUtzjD4GI567U_vh4g,23625
+onesecondtrader/monitoring/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/monitoring/console.py,sha256=1mrojXkyL4ro7ebkvDMGNQiCL-93WEylRuwnfmEKzVs,299
+onesecondtrader/monitoring/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader-0.8.0.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+onesecondtrader-0.8.0.dist-info/METADATA,sha256=ry6U-Hj4bxnaKgAWXdlM7CtL0Zv0w3_kri_NE2T-TzA,9518
+onesecondtrader-0.8.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+onesecondtrader-0.8.0.dist-info/RECORD,,

onesecondtrader-0.7.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-onesecondtrader/__init__.py,sha256=TNqlT20sH46-J7F6giBxwWYG1-wFZZt7toDbZeQK6KQ,210
-onesecondtrader/monitoring/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-onesecondtrader/monitoring/console.py,sha256=9_WrLnfG_IanqBX3FJQOy7ZYdceoTAXb5BXFYJTUq0o,298
-onesecondtrader-0.7.0.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-onesecondtrader-0.7.0.dist-info/METADATA,sha256=WXbgynzRnwqWMZerSQidFXiEtw5rZCWEiEw4XCjQn7E,9518
-onesecondtrader-0.7.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-onesecondtrader-0.7.0.dist-info/RECORD,,