xtrading-models 0.5.0__tar.gz

xtrading_models-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yanir Taflev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xtrading_models-0.5.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: xtrading-models
+Version: 0.5.0
+Summary: Shared trading models for XTrading ecosystem
+Author-email: Yanir Taflev <yanirta+xtrading@gmail.com>
+License: MIT
+Keywords: trading,models,finance,algotrading,backtesting
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# xtrading-models
+
+Shared trading models for the XTrading ecosystem.
+
+## Installation
+
+```bash
+pip install xtrading-models
+```
+
+## Usage
+
+```python
+from xtrading_models import MarketOrder, LimitOrder, BarData, UNSET_DOUBLE
+
+# Create a market order
+order = MarketOrder(action='BUY', totalQuantity=100)
+
+# Create bar data
+bar = BarData(
+    date=datetime.now(),
+    open=Decimal('100.00'),
+    high=Decimal('105.00'),
+    low=Decimal('99.00'),
+    close=Decimal('104.00'),
+    volume=1000000
+)
+```
+
+## Models
+
+- **Order classes**: `Order`, `LimitOrder`, `MarketOrder`, `StopOrder`, `StopLimitOrder`, `TrailingStopMarket`, `TrailingStopLimit`
+- **Bar data**: `BarData` - OHLCV candlestick representation
+- **Execution**: `Execution`, `CommissionReport`, `Fill`
+- **Results**: `ExecutionResult`
+- **Sentinels**: `UNSET_DOUBLE`, `UNSET_INTEGER`
+
+## License
+
+MIT

xtrading_models-0.5.0/README.md

@@ -0,0 +1,40 @@
+# xtrading-models
+
+Shared trading models for the XTrading ecosystem.
+
+## Installation
+
+```bash
+pip install xtrading-models
+```
+
+## Usage
+
+```python
+from xtrading_models import MarketOrder, LimitOrder, BarData, UNSET_DOUBLE
+
+# Create a market order
+order = MarketOrder(action='BUY', totalQuantity=100)
+
+# Create bar data
+bar = BarData(
+    date=datetime.now(),
+    open=Decimal('100.00'),
+    high=Decimal('105.00'),
+    low=Decimal('99.00'),
+    close=Decimal('104.00'),
+    volume=1000000
+)
+```
+
+## Models
+
+- **Order classes**: `Order`, `LimitOrder`, `MarketOrder`, `StopOrder`, `StopLimitOrder`, `TrailingStopMarket`, `TrailingStopLimit`
+- **Bar data**: `BarData` - OHLCV candlestick representation
+- **Execution**: `Execution`, `CommissionReport`, `Fill`
+- **Results**: `ExecutionResult`
+- **Sentinels**: `UNSET_DOUBLE`, `UNSET_INTEGER`
+
+## License
+
+MIT

xtrading_models-0.5.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "xtrading-models"
+version = "0.5.0"
+description = "Shared trading models for XTrading ecosystem"
+authors = [{name = "Yanir Taflev", email = "yanirta+xtrading@gmail.com"}]
+license = {text = "MIT"}
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+keywords = ["trading", "models", "finance", "algotrading", "backtesting"]
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest"
+]
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xtrading_models-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xtrading_models-0.5.0/src/xtrading_models/__init__.py

@@ -0,0 +1,22 @@
+from .order import (
+    Order, LimitOrder, MarketOrder, StopOrder, StopLimitOrder,
+    TrailingOrder, TrailingStopMarket, TrailingStopLimit,
+    UNSET_DOUBLE, UNSET_INTEGER
+)
+from .bar import BarData
+from .fill import Execution, CommissionReport, Fill
+from .execution_result import ExecutionResult
+
+__all__ = [
+    # Orders
+    'Order', 'LimitOrder', 'MarketOrder', 'StopOrder', 'StopLimitOrder',
+    'TrailingOrder', 'TrailingStopMarket', 'TrailingStopLimit',
+    # Sentinels
+    'UNSET_DOUBLE', 'UNSET_INTEGER',
+    # Bar
+    'BarData',
+    # Fill
+    'Execution', 'CommissionReport', 'Fill',
+    # Result
+    'ExecutionResult'
+]

xtrading_models-0.5.0/src/xtrading_models/bar.py

@@ -0,0 +1,38 @@
+from decimal import Decimal
+from datetime import datetime
+from pydantic import BaseModel, field_validator, model_validator
+
+
+class BarData(BaseModel):
+    """OHLCV bar data (IB-compatible) with validation."""
+
+    date: datetime
+    open: Decimal = Decimal('0')
+    high: Decimal = Decimal('0')
+    low: Decimal = Decimal('0')
+    close: Decimal = Decimal('0')
+    volume: int = 0
+    # average: Decimal = Decimal('0')
+    # barCount: int = 0
+
+    @field_validator('date')
+    @classmethod
+    def date_required(cls, v):
+        if v is None:
+            raise ValueError('date cannot be null')
+        return v
+
+    @model_validator(mode='after')
+    def validate_ohlc(self):
+        """Validate OHLC relationships: High >= all, Low <= all."""
+        if self.high < self.low:
+            raise ValueError(f'High ({self.high}) must be >= Low ({self.low})')
+        if self.high < self.open:
+            raise ValueError(f'High ({self.high}) must be >= Open ({self.open})')
+        if self.high < self.close:
+            raise ValueError(f'High ({self.high}) must be >= Close ({self.close})')
+        if self.low > self.open:
+            raise ValueError(f'Low ({self.low}) must be <= Open ({self.open})')
+        if self.low > self.close:
+            raise ValueError(f'Low ({self.low}) must be <= Close ({self.close})')
+        return self

xtrading_models-0.5.0/src/xtrading_models/execution_result.py

@@ -0,0 +1,36 @@
+"""Execution result model for order execution outcomes."""
+from dataclasses import dataclass, field
+
+from .order import Order
+from .fill import Fill
+
+
+@dataclass
+class ExecutionResult:
+    """Result of executing one or more orders against a bar."""
+    fills: list[Fill] = field(default_factory=list)
+    pending_orders: list[Order] = field(default_factory=list)
+
+    @property
+    def status(self) -> str:
+        """Derive overall status from fills and pending.
+
+        Returns:
+            - 'PENDING': No fills yet (order not executed or pending)
+            - 'FILLED': All orders filled, nothing pending
+            - 'PARTIAL': Some fills with pending orders (e.g., stop triggered, limit pending)
+        """
+        has_fills = len(self.fills) > 0
+        has_pending = len(self.pending_orders) > 0
+
+        if not has_fills and not has_pending:
+            # Should never happen - at minimum order should be pending
+            raise ValueError("Invalid ExecutionResult state: empty result")
+        if not has_fills and has_pending:
+            return 'PENDING'      # Order(s) not executed yet
+        if has_fills and not has_pending:
+            return 'FILLED'       # All done
+        if has_fills and has_pending:
+            return 'PARTIAL'      # Parent filled, children pending
+
+        raise ValueError("Unexpected ExecutionResult state")

xtrading_models-0.5.0/src/xtrading_models/fill.py

@@ -0,0 +1,55 @@
+from decimal import Decimal
+from dataclasses import dataclass
+from datetime import datetime
+from typing import NamedTuple, Optional
+
+from .order import Order
+
+
+@dataclass
+class Execution:
+    """Record of an order execution."""
+
+    execId: str = ''
+    time: Optional[datetime] = None
+    acctNumber: str = ''
+    exchange: str = ''
+    side: str = ''
+    shares: float = 0.0
+    price: Decimal = Decimal('0')
+    permId: int = 0
+    clientId: int = 0
+    orderId: int = 0
+    liquidation: int = 0
+    cumQty: float = 0.0
+    avgPrice: Decimal = Decimal('0')
+    orderRef: str = ''
+    evRule: str = ''
+    evMultiplier: float = 0.0
+    modelCode: str = ''
+    lastLiquidity: int = 0
+
+
+@dataclass
+class CommissionReport:
+    """Commission and P&L information for an execution."""
+
+    execId: str = ''
+    commission: Decimal = Decimal('0')
+    currency: str = ''
+    realizedPNL: Decimal = Decimal('0')
+    yield_: float = 0.0
+    yieldRedemptionDate: int = 0
+
+
+class Fill(NamedTuple):
+    """
+    Combines order, execution, and commission into a single record.
+    IB-compatible nested object.
+    """
+
+    order: Order
+    execution: Execution
+    commissionReport: CommissionReport
+    time: datetime
+    parentId: int = 0

xtrading_models-0.5.0/src/xtrading_models/order.py

@@ -0,0 +1,225 @@
+from decimal import Decimal
+from typing import Optional, ClassVar
+from pydantic import BaseModel, Field, model_validator, field_validator
+
+
+UNSET_DOUBLE = Decimal('inf')
+UNSET_INTEGER = 2**31 - 1
+
+
+class Order(BaseModel):
+    """Base order class for trading."""
+
+    model_config = {
+        'arbitrary_types_allowed': True,
+        'validate_assignment': True,  # Validate on mutation
+    }
+
+    _next_order_id: ClassVar[int] = 1
+
+    orderId: int = Field(default=0)
+    clientId: int = 0
+    action: str = ''
+    totalQuantity: float = 0.0
+    orderType: str = ''
+    price: Decimal = Field(default=UNSET_DOUBLE, allow_inf_nan=True)
+    tif: str = ''
+    goodTillDate: str = ''
+    goodAfterTime: str = ''
+    ocaGroup: str = ''
+    orderRef: str = ''
+    parentId: int = UNSET_INTEGER
+    transmit: bool = True
+    children: list['Order'] = Field(default_factory=list)
+
+    @field_validator('price', mode='before')
+    @classmethod
+    def allow_unset_price(cls, v):
+        """Allow UNSET_DOUBLE sentinel value."""
+        return v
+
+    def model_post_init(self, __context) -> None:
+        """Auto-assign orderId after initialization."""
+        if self.orderId == 0:
+            self.orderId = Order._next_order_id
+            Order._next_order_id += 1
+
+    def add_child(self, child: 'Order') -> None:
+        """Add a child order and set its parentId."""
+        child.parentId = self.orderId
+        self.children.append(child)
+
+class LimitOrder(Order):
+    """Limit order."""
+
+    @field_validator('price', mode='before')
+    @classmethod
+    def allow_unset_price(cls, v):
+        """Allow UNSET_DOUBLE sentinel value."""
+        return v
+
+    def __init__(self, action: str, totalQuantity: float, price: Decimal, **kwargs):
+        super().__init__(
+            orderType='LMT',
+            action=action,
+            totalQuantity=totalQuantity,
+            price=price,
+            **kwargs
+        )
+
+class MarketOrder(Order):
+    """Market order."""
+
+    def __init__(self, action: str, totalQuantity: float, **kwargs):
+        super().__init__(
+            orderType='MKT',
+            action=action,
+            totalQuantity=totalQuantity,
+            **kwargs
+        )
+
+class StopOrder(Order):
+    """Stop order implemented as Stop with Market child."""
+
+    def __init__(self, action: str, totalQuantity: float, stopPrice: Decimal, **kwargs):
+        # Initialize as a Stop order (parent)
+        super().__init__(
+            orderType='STP',
+            action=action,
+            totalQuantity=totalQuantity,
+            price=stopPrice,
+            **kwargs
+        )
+
+        # Create Market child order (orderId auto-assigned)
+        market_child = MarketOrder(
+            action=action,
+            totalQuantity=totalQuantity
+        )
+        self.add_child(market_child)
+
+class StopLimitOrder(Order):
+    """Stop limit order implemented as Stop with Limit child."""
+
+    def __init__(self, action: str, totalQuantity: float, limitPrice: Decimal, stopPrice: Decimal, **kwargs):
+        # Initialize as a Stop order (parent)
+        super().__init__(
+            orderType='STP LMT',  # Preserve backward compatibility
+            action=action,
+            totalQuantity=totalQuantity,
+            price=stopPrice,
+            **kwargs
+        )
+
+        # Create Limit child order (orderId auto-assigned)
+        limit_child = LimitOrder(
+            action=action,
+            totalQuantity=totalQuantity,
+            price=limitPrice
+        )
+        self.add_child(limit_child)
+
+class TrailingOrder(Order):
+    """Base class for trailing orders."""
+
+    trailingDistance: Optional[Decimal] = None
+    trailingPercent: Optional[Decimal] = None
+    stopPrice: Optional[Decimal] = None
+    extremePrice: Optional[Decimal] = None
+
+    @model_validator(mode='after')
+    def validate_trailing_params(self):
+        """Validate exactly one of trailingDistance or trailingPercent is set."""
+        if (self.trailingDistance is None and self.trailingPercent is None) or \
+           (self.trailingDistance is not None and self.trailingPercent is not None):
+            raise ValueError("Exactly one of trailingDistance or trailingPercent must be specified")
+        return self
+
+
+    def __init__(self, orderType: str, action: str, totalQuantity: float, trailingDistance: Optional[Decimal] = None, trailingPercent: Optional[Decimal] = None, **kwargs):
+        super().__init__(
+            orderType=orderType,
+            action=action,
+            totalQuantity=totalQuantity,
+            trailingDistance=trailingDistance, # type: ignore
+            trailingPercent=trailingPercent, # type: ignore
+            **kwargs
+        )
+
+class TrailingStopMarket(TrailingOrder):
+    """Trailing stop market order with mutable state tracking.
+
+    Tracks the extreme price and adjusts stop price as market moves favorably.
+    When stop is hit, the child Market order is executed.
+
+    Supports two modes (exactly one must be specified):
+    - trailingDistance: Absolute trailing amount (e.g., trail by $2.00)
+    - trailingPercent: Percentage trailing (e.g., trail by 2%)
+
+    Attributes:
+        trailingDistance: Absolute distance from extreme to stop (optional)
+        trailingPercent: Percentage distance from extreme to stop (optional)
+        currentStopPrice: Current stop trigger price (mutable)
+        extremePrice: Best price seen so far (mutable)
+        children: Contains one MarketOrder child
+    """
+    def __init__(self, action: str, totalQuantity: float, trailingDistance: Optional[Decimal] = None, trailingPercent: Optional[Decimal] = None, **kwargs):
+        super().__init__(
+            orderType='TRAIL',
+            action=action,
+            totalQuantity=totalQuantity,
+            trailingDistance=trailingDistance,
+            trailingPercent=trailingPercent,
+            **kwargs
+        )
+
+        # Create Market child order (will be executed when stop triggers)
+        market_child = MarketOrder(
+            action=action,
+            totalQuantity=totalQuantity
+        )
+        self.add_child(market_child)
+
+
+class TrailingStopLimit(TrailingOrder):
+    """Trailing stop limit order with mutable state tracking.
+
+    Similar to TrailingStopMarket but the child is a Limit order.
+
+    Supports two modes (exactly one must be specified):
+    - trailingDistance: Absolute trailing amount (e.g., trail by $2.00)
+    - trailingPercent: Percentage trailing (e.g., trail by 2%)
+
+    Attributes:
+        trailingDistance: Absolute distance from extreme to stop (optional)
+        trailingPercent: Percentage distance from extreme to stop (optional)
+        limitOffset: Distance from stop to limit price (always positive)
+        currentStopPrice: Current stop trigger price (mutable)
+        extremePrice: Best price seen so far (mutable)
+        children: Contains one LimitOrder child (price set when triggered)
+    """
+
+    limitOffset: Decimal = Decimal('0')
+
+    def __init__(self, action: str, totalQuantity: float,
+                 limitOffset: Decimal,
+                 trailingDistance: Optional[Decimal] = None,
+                 trailingPercent: Optional[Decimal] = None,
+                 **kwargs):
+        super().__init__(
+            orderType='TRAIL LIMIT',
+            action=action,
+            totalQuantity=totalQuantity,
+            trailingDistance=trailingDistance,
+            trailingPercent=trailingPercent,
+            limitOffset=limitOffset,
+            **kwargs
+        )
+
+        # Create Limit child order (price will be set when stop triggers)
+        limit_child = LimitOrder(
+            action=action,
+            totalQuantity=totalQuantity,
+            price=Decimal('0')  # Placeholder, set when stop triggers
+        )
+        self.add_child(limit_child)

xtrading_models-0.5.0/src/xtrading_models.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: xtrading-models
+Version: 0.5.0
+Summary: Shared trading models for XTrading ecosystem
+Author-email: Yanir Taflev <yanirta+xtrading@gmail.com>
+License: MIT
+Keywords: trading,models,finance,algotrading,backtesting
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# xtrading-models
+
+Shared trading models for the XTrading ecosystem.
+
+## Installation
+
+```bash
+pip install xtrading-models
+```
+
+## Usage
+
+```python
+from xtrading_models import MarketOrder, LimitOrder, BarData, UNSET_DOUBLE
+
+# Create a market order
+order = MarketOrder(action='BUY', totalQuantity=100)
+
+# Create bar data
+bar = BarData(
+    date=datetime.now(),
+    open=Decimal('100.00'),
+    high=Decimal('105.00'),
+    low=Decimal('99.00'),
+    close=Decimal('104.00'),
+    volume=1000000
+)
+```
+
+## Models
+
+- **Order classes**: `Order`, `LimitOrder`, `MarketOrder`, `StopOrder`, `StopLimitOrder`, `TrailingStopMarket`, `TrailingStopLimit`
+- **Bar data**: `BarData` - OHLCV candlestick representation
+- **Execution**: `Execution`, `CommissionReport`, `Fill`
+- **Results**: `ExecutionResult`
+- **Sentinels**: `UNSET_DOUBLE`, `UNSET_INTEGER`
+
+## License
+
+MIT

xtrading_models-0.5.0/src/xtrading_models.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/xtrading_models/__init__.py
+src/xtrading_models/bar.py
+src/xtrading_models/execution_result.py
+src/xtrading_models/fill.py
+src/xtrading_models/order.py
+src/xtrading_models.egg-info/PKG-INFO
+src/xtrading_models.egg-info/SOURCES.txt
+src/xtrading_models.egg-info/dependency_links.txt
+src/xtrading_models.egg-info/requires.txt
+src/xtrading_models.egg-info/top_level.txt
+tests/test_bar.py
+tests/test_fill.py
+tests/test_models.py

xtrading_models-0.5.0/src/xtrading_models.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xtrading_models-0.5.0/src/xtrading_models.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pydantic>=2.0
+
+[dev]
+pytest

xtrading_models-0.5.0/src/xtrading_models.egg-info/top_level.txt

@@ -0,0 +1 @@
+xtrading_models