mxm-refdata 0.3.0__py3-none-any.whl

mxm/refdata/models/products/futures_product.py

@@ -0,0 +1,38 @@
+"""DataClass for a futures product."""
+
+from dataclasses import dataclass
+
+from mxm.refdata.models.currencies import Currency
+from mxm.refdata.models.periods import PeriodType
+from mxm.refdata.models.products.settlement import SettlementMethod
+from mxm.refdata.models.units import ProductUnit
+
+
+@dataclass(frozen=True)
+class FuturesProduct:
+    """Represents a tradeable futures product."""
+
+    product_id: str  # Internal product code (aligned with venue's default code)
+    venue: str  # The venue (e.g., exchange or counterparty) offering the product
+    description: str  # Long-form name and/or description
+    currency: Currency  # Currency of the product (from Currency enum)
+    unit: ProductUnit  # Physical unit (from ProductUnit enum)
+    contract_size: float  # Number of physical units per contract
+    valid_period_rule: (
+        str  # Rule for determining valid trading periods (e.g., "FGHJKMNQUVXZ")
+    )
+    listing_rule: (
+        str  # Rule for determining available contracts (e.g., "monthly for all months")
+    )
+    period_types: tuple[PeriodType, ...]
+    settlement: SettlementMethod  # Settlement type (physical, financial, etc.)
+    last_trading_rule: str  # Rule for determining last trading day (e.g., "3rd last business day of delivery month")
+    expiry_rule: str  # Rule for determining contract expiry (e.g., "3rd Friday of delivery month")
+    trading_calendar: (
+        str  # Placeholder for the trading calendar rule (e.g. CME default)
+    )
+    trading_hours: str | None = None  # String representation of trading hours
+    tick_size: float | None = None
+    tick_value: float | None = None
+    initial_margin: float | None = None
+    maintenance_margin: float | None = None

mxm/refdata/models/products/settlement.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+
+class SettlementMethod(Enum):
+    """Settlement methods for FuturesProducts."""
+
+    PHYSICAL = "physical"
+    FINANCIAL = "financial"
+    CASH = "cash"
+    OTHER = "other"

mxm/refdata/models/reference_events.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+
+class ReferenceEvent(Enum):
+    """Enum representing the possible reference events for last trading day rules."""
+
+    BUSINESS_DAY_OF_PERIOD = "business_day_of_period"
+    CALENDAR_DAY_OF_PERIOD = "calendar_day_of_period"
+    WEEKDAY_OF_PERIOD = "weekday_of_period"

mxm/refdata/models/units.py

@@ -0,0 +1,28 @@
+"""Physical Units for Product and Contract denomination."""
+
+from enum import Enum
+
+
+class ProductUnit(Enum):
+    """Enumeration of physical units for various financial contracts."""
+
+    LOT = "Lot"  # General unit for futures or contracts representing multiple shares, bonds, or other assets
+    NOTIONAL = "Notional Value"  # Used to represent the face value for bond contracts
+    SHARE = "Share"  # Used when trading the underlying equity (e.g., spot transactions)
+    BOND = "Bond"  # Spot trading of a single bond (typically unusual; bonds are often traded in lots)
+    BARREL = "Barrel"  # Oil and other liquid commodities
+    TONNE = "Tonne"  # Bulk commodities like metals, grains
+    BUSHEL = "Bushel"  # Agricultural commodities
+    TROY_OUNCE = "Troy Ounce"  # Precious metals (e.g., gold, silver)
+    MWH = "Megawatt-hour"  # Electricity
+    GALLON = "Gallon"  # Energy products (e.g., gasoline)
+    CUBIC_METER = "Cubic Meter"  # Natural gas
+    CONTRACT = "Contract"  # General for options, swaps, and other derivatives
+    OUNCE = "Ounce"  # General mass unit (e.g., for agricultural products)
+    GRAM = "Gram"  # For precious metals and small-scale commodities
+    LITER = "Liter"  # Volume-based commodities
+    METRIC_TON = "Metric Ton"  # Alternative to tonne
+    CURRENCY_UNIT = "Currency Unit"  # For FX contracts (e.g., USD, EUR)
+    INDEX_POINT = "Index Point"  # For index-based contracts
+    MMBTU = "MMBtu"  # Natural gas
+    GBP = "GBP"  # British Pound Sterling (FX Futures)

mxm/refdata/models/weekdays.py

@@ -0,0 +1,66 @@
+"""A data-class encapsulating weekdays and different representations."""
+
+from dataclasses import dataclass
+
+WEEKDAY_STRINGS = {
+    0: "Monday",
+    1: "Tuesday",
+    2: "Wednesday",
+    3: "Thursday",
+    4: "Friday",
+    5: "Saturday",
+    6: "Sunday",
+}
+
+WEEKDAY_STRINGS_ABBR = {
+    0: "Mon",
+    1: "Tue",
+    2: "Wed",
+    3: "Thu",
+    4: "Fri",
+    5: "Sat",
+    6: "Sun",
+}
+
+WEEKDAY_LOOKUP = {
+    **{v.lower(): k for k, v in WEEKDAY_STRINGS.items()},  # Full names
+    **{v.lower(): k for k, v in WEEKDAY_STRINGS_ABBR.items()},  # Abbreviations
+}
+
+
+@dataclass(frozen=True)
+class Weekday:
+    """Represents a weekday with various representations."""
+
+    weekday: int  # 0 (Monday) to 6 (Sunday)
+
+    def __post_init__(self):
+        if not (0 <= self.weekday <= 6):
+            raise ValueError(
+                f"Invalid weekday: {self.weekday}. Must be between 0 (Monday) and 6 (Sunday)."
+            )
+
+    @property
+    def as_int(self) -> int:
+        """Return the weekday as an integer."""
+        return self.weekday
+
+    @property
+    def as_str(self) -> str:
+        """Return the weekday as a full name."""
+        return WEEKDAY_STRINGS[self.weekday]
+
+    @property
+    def as_abbr(self) -> str:
+        """Return the weekday as a three-letter abbreviation."""
+        return WEEKDAY_STRINGS_ABBR[self.weekday]
+
+    @classmethod
+    def from_str(cls, weekday_str: str) -> "Weekday":
+        """Create a Weekday instance from a full name or abbreviation."""
+        weekday_int = WEEKDAY_LOOKUP.get(weekday_str.lower())
+        if weekday_int is None:
+            raise ValueError(
+                f"Invalid weekday name: {weekday_str}. Expected one of {list(WEEKDAY_LOOKUP.keys())}."
+            )
+        return cls(weekday_int)

mxm/refdata/parsing/__init__.py

@@ -0,0 +1 @@
+"""Parsing logic from external sources to internal normalised data."""

mxm/refdata/parsing/futures_products_from_csv.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import csv
+
+from mxm.refdata.models.currencies import Currency
+from mxm.refdata.models.products.futures_product import FuturesProduct, SettlementMethod
+from mxm.refdata.models.units import ProductUnit
+from mxm.refdata.utils.period_types_codec import decode_period_types
+
+
+def parse_futures_products_csv(csv_file_path: str) -> list[FuturesProduct]:
+    """Parse futures_products.csv into FuturesProduct domain objects."""
+    required_fields = {
+        "product_id",
+        "venue",
+        "description",
+        "currency",
+        "unit",
+        "contract_size",
+        "valid_period_rule",
+        "listing_rule",
+        "period_types",
+        "settlement",
+        "last_trading_rule",
+        "expiry_rule",
+        "trading_calendar",
+        "trading_hours",
+        "tick_size",
+        "tick_value",
+        "initial_margin",
+        "maintenance_margin",
+    }
+
+    def _fopt(x: str | None) -> float | None:
+        s = (x or "").strip()
+        return float(s) if s else None
+
+    def _freq(x: str | None, field: str) -> float:
+        s = (x or "").strip()
+        if not s:
+            raise ValueError(f"required numeric field {field!r} is empty")
+        return float(s)
+
+    with open(csv_file_path, encoding="utf-8-sig") as csvfile:
+        reader = csv.DictReader(csvfile)
+        products: list[FuturesProduct] = []
+
+        for row in reader:
+            missing_fields = required_fields - set(row.keys())
+            if missing_fields:
+                raise ValueError(f"Missing required fields in CSV: {missing_fields}")
+
+            products.append(
+                FuturesProduct(
+                    product_id=row["product_id"],
+                    venue=row["venue"],
+                    description=row["description"],
+                    currency=Currency[row["currency"]],
+                    unit=ProductUnit[row["unit"]],
+                    contract_size=_freq(row.get("contract_size"), "contract_size"),
+                    valid_period_rule=row["valid_period_rule"],
+                    listing_rule=row["listing_rule"],
+                    period_types=decode_period_types(row["period_types"]),
+                    settlement=SettlementMethod[row["settlement"]],
+                    last_trading_rule=row["last_trading_rule"],
+                    expiry_rule=row["expiry_rule"],
+                    trading_calendar=row["trading_calendar"],
+                    trading_hours=(row.get("trading_hours") or "").strip() or None,
+                    tick_size=_fopt(row.get("tick_size")),
+                    tick_value=_fopt(row.get("tick_value")),
+                    initial_margin=_fopt(row.get("initial_margin")),
+                    maintenance_margin=_fopt(row.get("maintenance_margin")),
+                )
+            )
+
+    return products

mxm/refdata/scripts/__init__.py

@@ -0,0 +1 @@
+"""Scripts using refData functionality."""

mxm/refdata/scripts/db_utils.py

@@ -0,0 +1,61 @@
+"""CLI script for managing the database."""
+
+import argparse
+import logging
+
+from mxm.refdata.database.sql_session_manager import SQLSessionManager
+
+logging.basicConfig(level=logging.INFO)
+
+
+def main():
+    """Command-line interface for database management."""
+    parser = argparse.ArgumentParser(description="Database management script.")
+    parser.add_argument(
+        "--init", action="store_true", help="Initialize the database schema."
+    )
+    parser.add_argument(
+        "--drop", action="store_true", help="Drop all tables in the database."
+    )
+    parser.add_argument(
+        "--check", action="store_true", help="Check the database connection."
+    )
+
+    args = parser.parse_args()
+
+    # Use the default SQLSessionManager instance
+    session_manager = SQLSessionManager()
+
+    if args.init:
+        success = session_manager.init_db()
+        if success:
+            logging.info("Database initialized successfully.")
+        else:
+            logging.error("Failed to initialize the database.")
+
+    elif args.drop:
+        confirmation = input(
+            "WARNING: This will delete all data in the database! Type 'yes' to confirm: "
+        )
+        if confirmation.lower() == "yes":
+            success = session_manager.drop_db()
+            if success:
+                logging.info("Database dropped successfully.")
+            else:
+                logging.error("Failed to drop the database.")
+        else:
+            logging.info("Database drop operation aborted.")
+
+    elif args.check:
+        success = session_manager.check_db_connection()
+        if success:
+            logging.info("Database connection is active.")
+        else:
+            logging.error("Database connection check failed.")
+
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

mxm/refdata/scripts/manage_static_ref_data.py

@@ -0,0 +1,73 @@
+"""Manage the static reference data in the database."""
+
+import argparse
+import logging
+from datetime import date
+
+from mxm.refdata.database.sql_session_manager import SQLSessionManager
+from mxm.refdata.services.ref_data_service import RefDataService
+from mxm.refdata.utils.config import load_config
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+def main():
+    """CLI script to manage reference data: reset and initialize database."""
+    # Load default config
+    config = load_config()
+    default_csv_path = (
+        config.REFDATA_FUTURES_PRODUCTS_CSV_PATH or "data/futures_products.csv"
+    )
+
+    # Argument parser
+    parser = argparse.ArgumentParser(description="Manage the reference data database.")
+    parser.add_argument(
+        "--reset",
+        action="store_true",
+        help="Reset the database before initializing (WARNING: This deletes all existing data!).",
+    )
+    parser.add_argument(
+        "--csv",
+        type=str,
+        default=default_csv_path,
+        help=f"Path to the CSV file for futures products (default: {default_csv_path}).",
+    )
+    parser.add_argument(
+        "--start-date",
+        type=lambda s: date.fromisoformat(s),
+        default=date(2000, 1, 1),
+        help="Start date for period and contract initialization (format: YYYY-MM-DD, default: 2000-01-01).",
+    )
+    parser.add_argument(
+        "--end-date",
+        type=lambda s: date.fromisoformat(s),
+        default=date(2045, 12, 31),
+        help="End date for period and contract initialization (format: YYYY-MM-DD, default: 2045-12-31).",
+    )
+
+    args = parser.parse_args()
+
+    logger.info("Initializing Reference Data Service...")
+    session_manager = SQLSessionManager()
+    ref_data_service = RefDataService(session_manager=session_manager)
+
+    # Optionally reset the database
+    if args.reset:
+        logger.warning("Resetting the database. All existing data will be deleted!")
+        ref_data_service.reset_database()
+
+    # Initialize reference data
+    logger.info("Starting reference data setup...")
+    ref_data_service.setup_instruments(
+        csv_file_path=args.csv, start_date=args.start_date, end_date=args.end_date
+    )
+    logger.info("Reference data initialization completed successfully.")
+
+
+if __name__ == "__main__":
+    main()

mxm/refdata/services/bootstrap.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from datetime import date
+
+from sqlalchemy.exc import SQLAlchemyError
+
+from mxm.refdata.database.sql_session_manager import SQLSessionManager
+from mxm.refdata.models.orm.futures_products import FuturesProductORM
+from mxm.refdata.utils.config import Config
+
+
+class RefDataNotInitialisedError(RuntimeError):
+    """Raised when refdata is required but DB auto-initialisation is forbidden."""
+
+
+def _db_has_any_products(session_manager: SQLSessionManager) -> bool:
+    try:
+        with session_manager.db_session_scope() as session:
+            return session.query(FuturesProductORM).limit(1).first() is not None
+    except SQLAlchemyError:
+        return False
+
+
+def build_refdata(
+    *,
+    session_manager: SQLSessionManager | None = None,
+    csv_file_path: str | None = None,
+    start_date: date | None = None,
+    end_date: date | None = None,
+) -> None:
+    """Build the refdata database without first dropping existing tables."""
+    from mxm.refdata.services.ref_data_service import RefDataService
+
+    sm = session_manager or SQLSessionManager()
+    sm.init_db()
+
+    RefDataService(session_manager=sm).setup_instruments(
+        csv_file_path=csv_file_path,
+        start_date=start_date,
+        end_date=end_date,
+    )
+
+
+def rebuild_refdata(
+    *,
+    session_manager: SQLSessionManager | None = None,
+    csv_file_path: str | None = None,
+    start_date: date | None = None,
+    end_date: date | None = None,
+) -> None:
+    """Destructively rebuild the refdata database."""
+    from mxm.refdata.services.ref_data_service import RefDataService
+
+    sm = session_manager or SQLSessionManager()
+    svc = RefDataService(session_manager=sm)
+
+    svc.reset_database()
+    svc.setup_instruments(
+        csv_file_path=csv_file_path,
+        start_date=start_date,
+        end_date=end_date,
+    )
+
+
+def ensure_refdata_ready(session_manager: SQLSessionManager, cfg: Config) -> None:
+    """
+    Ensure the refdata DB is initialised and populated.
+
+    If already populated, this is a no-op. If empty and buildable, the packaged
+    ontology is materialised. If managed, missing refdata is an error.
+    """
+    if _db_has_any_products(session_manager):
+        return
+
+    if cfg.REFDATA_DB_MODE != "buildable":
+        raise RefDataNotInitialisedError(
+            "Refdata database is not initialised and auto-creation is forbidden "
+            f"(REFDATA_DB_MODE={cfg.REFDATA_DB_MODE!r}). Initialise refdata explicitly."
+        )
+
+    build_refdata(
+        session_manager=session_manager,
+        csv_file_path=cfg.REFDATA_FUTURES_PRODUCTS_CSV_PATH,
+    )

mxm/refdata/services/futures_contract_factory.py

@@ -0,0 +1,127 @@
+"""Factory to create futures contracts."""
+
+import datetime
+import threading
+from typing import ClassVar
+
+from mxm.refdata.models.contracts.futures_contract import FuturesContract
+from mxm.refdata.models.months import Month
+from mxm.refdata.models.periods import Period, PeriodType
+from mxm.refdata.models.products.futures_product import FuturesProduct
+from mxm.refdata.trading_calendars.first_day_of_interest import (
+    calculate_first_day_of_interest,
+)
+from mxm.refdata.trading_calendars.last_trading_day import calculate_last_trading_day
+from mxm.refdata.trading_calendars.trading_calendar import TradingCalendar
+
+
+class FuturesContractFactory:
+    """Factory for generating and retrieving FuturesContract instances."""
+
+    _instance = None  # Singleton instance
+    _lock = threading.Lock()  # Lock for thread safety
+    _cache: ClassVar[dict[str, FuturesContract]] = {}  # Cache for created contracts
+
+    def __new__(cls) -> "FuturesContractFactory":
+        """Ensures only one instance of FuturesContractFactory is created."""
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def create_contracts_for_product(
+        self, product: FuturesProduct, available_periods: dict[str, Period]
+    ) -> list[FuturesContract]:
+        """
+        Create all FuturesContract objects for a given product using available periods.
+
+        Args:
+            product (FuturesProduct): The product for which contracts are created.
+            available_periods (Dict[str, Period]): Dictionary of period_id -> Period instances.
+
+        Returns:
+            list[FuturesContract]: A list of valid FuturesContract objects.
+        """
+        contracts: list[FuturesContract] = []
+
+        for period in available_periods.values():
+            if period.period_type not in product.period_types:
+                continue  # Skip periods that don't match product requirements
+
+            if self._is_valid_period(product, period):
+                contract_id = self._create_contract_id(
+                    product.product_id, period.period_id
+                )
+
+                if contract_id not in self._cache:
+                    contract = self.create_contract(product, period)
+                    self._cache[contract_id] = contract
+                else:
+                    contract = self._cache[contract_id]
+
+                contracts.append(contract)
+
+        return contracts
+
+    def _is_valid_period(self, product: FuturesProduct, period: Period) -> bool:
+        """
+        Determine whether a period is valid for a given product based on valid_period_rule.
+
+        Args:
+            product (FuturesProduct): The product being evaluated.
+            period (Period): The period being checked.
+
+        Returns:
+            bool: True if the period is valid for the product.
+        """
+        if period.period_type == PeriodType.MONTH:
+            return (
+                Month(period.first_date.month).as_cme_code in product.valid_period_rule
+            )
+
+        return True
+
+    def clear_cache(self):
+        """Clear the cache of created contracts."""
+        self._cache.clear()
+
+    def _create_contract_id(self, product_id: str, period_id: str) -> str:
+        """Create a unique contract ID from product and period IDs."""
+        return f"{product_id}.{period_id}"
+
+    def create_contract(
+        self, product: FuturesProduct, period: Period
+    ) -> FuturesContract:
+        """
+        Create a FuturesContract object for a given product and period.
+
+        Args:
+            product (FuturesProduct): The product for which the contract is created.
+            period (Period): The delivery period for the contract.
+
+        Returns:
+            FuturesContract: A valid FuturesContract object.
+        """
+        trading_calendar = TradingCalendar(
+            product.trading_calendar,
+            start=datetime.date(1980, 1, 1),
+            end=datetime.date(2046, 12, 31),
+        )
+        last_trading_day = calculate_last_trading_day(
+            product.product_id, period, trading_calendar
+        )
+        first_day_of_interest = calculate_first_day_of_interest(
+            product.product_id, period, trading_calendar
+        )
+
+        return FuturesContract(
+            product_id=product.product_id,
+            period_id=period.period_id,
+            contract_id=self._create_contract_id(product.product_id, period.period_id),
+            contract_size=product.contract_size,
+            currency=product.currency,
+            unit=product.unit,
+            trading_calendar=product.trading_calendar,
+            first_day_of_interest=first_day_of_interest,
+            last_trading_day=last_trading_day,
+        )