mxm-refdata 0.3.0__py3-none-any.whl

mxm/refdata/cli.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import datetime as dt
+from datetime import date
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from mxm.refdata.api.ref_data_api import RefDataAPI
+from mxm.refdata.services.bootstrap import build_refdata, rebuild_refdata
+from mxm.refdata.services.smokecheck import run_smokechecks
+
+app = typer.Typer(
+    add_completion=False,
+    help="Inspect and materialize MXM reference data.",
+)
+
+console = Console()
+
+
+def parse_cli_date(value: str) -> date:
+    """Parse a CLI date in YYYY-MM-DD format."""
+    try:
+        return dt.datetime.strptime(value, "%Y-%m-%d").date()
+    except ValueError as err:
+        raise typer.BadParameter("Expected date in YYYY-MM-DD format.") from err
+
+
+@app.command("build")
+def build() -> None:
+    """Build the local reference-data database."""
+    build_refdata()
+    console.print("[green]Reference data database built.[/]")
+
+
+@app.command("rebuild")
+def rebuild() -> None:
+    """Destructively rebuild the local reference-data database."""
+    rebuild_refdata()
+    console.print("[green]Reference data database rebuilt.[/]")
+
+
+@app.command("products")
+def products() -> None:
+    """List available futures products."""
+    api = RefDataAPI()
+    rows = api.get_all_products()
+
+    table = Table(title="MXM Futures Products")
+    table.add_column("Product ID")
+    table.add_column("Venue")
+    table.add_column("Currency")
+    table.add_column("Unit")
+    table.add_column("Period Types")
+
+    for product in rows:
+        table.add_row(
+            product.product_id,
+            product.venue,
+            product.currency.value,
+            product.unit.value,
+            ", ".join(period_type.value for period_type in product.period_types),
+        )
+
+    console.print(table)
+
+
+@app.command("product")
+def product(
+    product_id: Annotated[str, typer.Argument(help="Canonical product ID")],
+) -> None:
+    """Show one futures product."""
+    api = RefDataAPI()
+    product_obj = api.get_product_by_id(product_id)
+
+    table = Table(title=f"Product: {product_obj.product_id}")
+    table.add_column("Field")
+    table.add_column("Value")
+
+    table.add_row("product_id", product_obj.product_id)
+    table.add_row("venue", product_obj.venue)
+    table.add_row("description", product_obj.description)
+    table.add_row("currency", product_obj.currency.value)
+    table.add_row("unit", product_obj.unit.value)
+    table.add_row("contract_size", str(product_obj.contract_size))
+    table.add_row("listing_rule", product_obj.listing_rule)
+    table.add_row(
+        "period_types",
+        ", ".join(period_type.value for period_type in product_obj.period_types),
+    )
+    table.add_row("settlement", product_obj.settlement.value)
+    table.add_row("last_trading_rule", product_obj.last_trading_rule)
+    table.add_row("expiry_rule", product_obj.expiry_rule)
+    table.add_row("trading_calendar", product_obj.trading_calendar)
+    table.add_row("tick_size", str(product_obj.tick_size))
+    table.add_row("tick_value", str(product_obj.tick_value))
+    table.add_row("valid_period_rule", product_obj.valid_period_rule)
+
+    console.print(table)
+
+
+@app.command("contracts")
+def contracts(
+    product_id: Annotated[str, typer.Argument(help="Canonical product ID")],
+) -> None:
+    """List contracts for a futures product."""
+    api = RefDataAPI()
+    rows = api.get_contracts_for_product(product_id)
+
+    table = Table(title=f"Contracts: {product_id}")
+    table.add_column("Contract ID")
+    table.add_column("Period")
+    table.add_column("First Interest")
+    table.add_column("Last Trading")
+
+    for contract in rows:
+        table.add_row(
+            contract.contract_id,
+            contract.period_id,
+            contract.first_day_of_interest.isoformat(),
+            contract.last_trading_day.isoformat(),
+        )
+
+    console.print(table)
+
+
+@app.command("active")
+def active(
+    as_of_date: Annotated[str, typer.Argument(help="Date in YYYY-MM-DD format")],
+    product_id: Annotated[str | None, typer.Option(help="Optional product ID")] = None,
+) -> None:
+    """List active contracts as of a date."""
+    parsed_date = parse_cli_date(as_of_date)
+    api = RefDataAPI()
+    rows = api.get_active_contracts(parsed_date, product_id=product_id)
+
+    table = Table(title=f"Active contracts: {parsed_date.isoformat()}")
+    table.add_column("Product ID")
+    table.add_column("Contract ID")
+    table.add_column("Period")
+    table.add_column("Last Trading")
+
+    for contract in rows:
+        table.add_row(
+            contract.product_id,
+            contract.contract_id,
+            contract.period_id,
+            contract.last_trading_day.isoformat(),
+        )
+
+    console.print(table)
+
+
+@app.command("coverage")
+def coverage() -> None:
+    """Show contract coverage by product."""
+    api = RefDataAPI()
+    products = api.get_all_products()
+
+    table = Table(title="MXM Refdata Coverage")
+    table.add_column("Product ID")
+    table.add_column("Venue")
+    table.add_column("First Contract")
+    table.add_column("Last Contract")
+    table.add_column("Count", justify="right")
+
+    for product_obj in products:
+        product_contracts = api.get_contracts_for_product(product_obj.product_id)
+
+        if not product_contracts:
+            table.add_row(product_obj.product_id, product_obj.venue, "-", "-", "0")
+            continue
+
+        table.add_row(
+            product_obj.product_id,
+            product_obj.venue,
+            product_contracts[0].contract_id,
+            product_contracts[-1].contract_id,
+            str(len(product_contracts)),
+        )
+
+    console.print(table)
+
+
+@app.command("smokecheck")
+def smokecheck() -> None:
+    """Run operational smoke checks against the local refdata database."""
+    report = run_smokechecks()
+
+    console.print("[bold]MXM Refdata Smokecheck[/bold]")
+    console.print(
+        "Counts: "
+        f"products={report.counts.products}, "
+        f"periods={report.counts.periods}, "
+        f"contracts={report.counts.contracts}, "
+        f"cycles={report.counts.cycles}, "
+        f"memberships={report.counts.memberships}"
+    )
+
+    table = Table(title="Smokecheck Results")
+    table.add_column("Status")
+    table.add_column("Check")
+    table.add_column("Message")
+
+    for result in report.results:
+        status = "[green]PASS[/]" if result.status == "pass" else "[red]FAIL[/]"
+        table.add_row(status, result.name, result.message)
+
+    console.print(table)
+
+    if not report.passed:
+        raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    app()

mxm/refdata/data/first_day_of_interest_rule.json

@@ -0,0 +1,88 @@
+{
+    "comex_gold_futures": {
+      "shift_rule": {
+        "shift_period_type": "MONTH",
+        "n_shift": {
+          "Jan": 72,
+          "Feb": 24,
+          "Mar": 24,
+          "Apr": 24,
+          "May": 24,
+          "Jun": 72,
+          "Jul": 24,
+          "Aug": 24,
+          "Sep": 24,
+          "Oct": 24,
+          "Nov": 24,
+          "Dec": 72
+        }
+      },
+      "reference_rule": "next_b_day_after_period"
+    },
+    "cbot_corn_futures": {
+      "shift_rule": {
+        "shift_period_type": "MONTH",
+        "n_shift": {
+          "Mar": 36,
+          "May": 36,
+          "Sep": 36,
+          "Jul": 48,
+          "Dec": 48
+        }
+      },
+      "reference_rule": "next_b_day_after_last_trading_day_of_december"
+    },
+    "cme_gbp_futures": {
+      "shift_rule": {
+        "shift_period_type": "MONTH",
+        "n_shift": {
+          "Mar": 60,
+          "Jun": 60,
+          "Sep": 60,
+          "Dec": 60,
+          "Jan": 3,
+          "Feb": 3,
+          "Apr": 3,
+          "May": 3,
+          "Jul": 3,
+          "Aug": 3,
+          "Oct": 3,
+          "Nov": 3
+        }
+      },
+      "reference_rule": "next_b_day_after_period"
+    },
+    "cme_emini_snp500_futures": {
+      "shift_rule": {
+        "shift_period_type": "MONTH",
+        "n_shift": {
+          "Mar": 63,
+          "Jun": 63,
+          "Sep": 63,
+          "Dec": 63
+        }
+      },
+      "reference_rule": "next_b_day_after_period"
+    },
+    "nymex_natural_gas_futures": {
+      "shift_rule": {
+        "shift_period_type": "MONTH",
+        "n_shift": {
+          "Jan": 144,
+          "Feb": 144,
+          "Mar": 144,
+          "Apr": 144,
+          "May": 144,
+          "Jun": 144,
+          "Jul": 144,
+          "Aug": 144,
+          "Sep": 144,
+          "Oct": 144,
+          "Nov": 144,
+          "Dec": 144
+        }
+      },
+      "reference_rule": "next_b_day_after_last_trading_day_of_december"
+    }
+  }
+  

mxm/refdata/data/futures_products.csv

@@ -0,0 +1,6 @@
+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
+comex_gold_futures,COMEX,Gold Futures,USD,TROY_OUNCE,100,FGHJKMNQUVXZ,Monthly contracts listed for 24 consecutive months and any Jun and Dec in the nearest 72 months.,MONTH,PHYSICAL,Trading terminates at 12:30 p.m. CT on the third last business day of the contract month.,last business day of the contract month.,CMES,Sunday - Friday 6:00 p.m. - 5:00 p.m. (5:00 p.m. - 4:00 p.m. /CT) with a 60-minute break each day beginning at 5:00 p.m. (4:00 p.m. CT),0.1,10,,
+cbot_corn_futures,CBOT,Corn Futures,USD,BUSHEL,5000,HKNUZ,"9 monthly contracts of Mar, May, Sep and 8 monthly contracts of Jul and Dec listed annually after the termination of trading in the December contract of the current year.",MONTH,PHYSICAL,Trading terminates on the business day prior to the 15th day of the contract month.,Second business day following the last trading day of the delivery month.,CMES,Sunday - Friday: 7:00 p.m. - 7:45 a.m. CT and Monday - Friday: 8:30 a.m. - 1:20 p.m. CT,0.0025,12.5,,
+cme_gbp_futures,CME,British Pound Futures,USD,GBP,62500,FGHJKMNQUVXZ,"Quarterly contracts (Mar, Jun, Sep, Dec) listed for 20 consecutive quarters and serial contracts listed for 3 months",MONTH,PHYSICAL,"Trading terminates at 9:16 a.m. CT, 2 business days prior to the third Wednesday of the contract month.",2 business days prior to the third Wednesday of the contract month.,CMES,Sunday - Friday 6:00 p.m. - 5:00 p.m. (5:00 p.m. - 4:00 p.m. CT) with a 60-minute break each day beginning at 5:00 p.m. (4:00 p.m. CT).,0.0001,6.25,,
+cme_emini_snp500_futures,CME,S&P 500 E-mini Futures,USD,INDEX_POINT,50,HMUZ,"Quarterly contracts (Mar, Jun, Sep, Dec) listed for 21 consecutive quarters",MONTH,FINANCIAL,Trading terminates at 9:30 a.m. ET on the 3rd Friday of the contract month.,3rd Friday of the contract month.,CMES,Sunday 6:00 p.m. - Friday 5:00 p.m. ET (5:00 p.m. - 4:00 p.m. CT) with a daily maintenance period from 5:00 p.m. - 6:00 p.m. ET (4:00 p.m. - 5:00 p.m. CT),0.25,12.5,,
+nymex_natural_gas_futures,NYMEX,HH Natural Gas Futures,USD,MMBTU,10000,FGHJKMNQUVXZ,Monthly contracts listed for the current year and the next 12 calendar years. List monthly contracts for a new calendar year following the termination of trading in the December contract of the current year.,MONTH,PHYSICAL,Trading terminates on the 3rd last business day of the month prior to the contract month. ,3rd last business day of the contract month.,CMES,Sunday - Friday 6:00 p.m. - 5:00 p.m. (5:00 p.m. - 4:00 p.m. CT) with a 60-minute break each day beginning at 5:00 p.m. (4:00 p.m. CT).,0.001,10,,

mxm/refdata/data/last_trading_rule.json

@@ -0,0 +1,34 @@
+{
+    "comex_gold_futures": {
+        "period_offset": 0,
+        "reference_event": "business_day_of_period",
+        "n_reference": -3,
+        "business_day_offset": 0
+    },
+    "cbot_corn_futures": {
+        "period_offset": 0,
+        "reference_event": "calendar_day_of_period",
+        "n_reference": 15,
+        "business_day_offset": -1
+    },
+    "cme_gbp_futures": {
+        "period_offset": 0,
+        "reference_event": "weekday_of_period",
+        "n_reference": 3,
+        "weekday": "Wednesday",
+        "business_day_offset": -2
+    },
+    "cme_emini_snp500_futures": {
+        "period_offset": 0,
+        "reference_event": "weekday_of_period",
+        "n_reference": 3,
+        "weekday": "Friday",
+        "business_day_offset": 0
+    },
+    "nymex_natural_gas_futures": {
+        "period_offset": -1,
+        "reference_event": "business_day_of_period",
+        "n_reference": -3,
+        "business_day_offset": 0
+    }
+}

mxm/refdata/database/__init__.py

@@ -0,0 +1 @@
+"""Database integration for refData."""

mxm/refdata/database/sql_session_manager.py

@@ -0,0 +1,135 @@
+"""SQL Session Manager for handling database interactions."""
+
+import logging
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from sqlalchemy import Engine, create_engine
+from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.sql import text
+
+from mxm.refdata.models.orm import Base
+from mxm.refdata.utils.config import load_config
+
+logging.basicConfig(level=logging.INFO)
+
+
+class SQLSessionManager:
+    """Manages database sessions while ensuring consistent engine initialization."""
+
+    def __init__(
+        self,
+        db_url: str | None = None,
+        engine: Engine | None = None,
+        session_factory: Callable[[], Session] | None = None,
+    ):
+        """
+        Initialize the SQLSessionManager with a specific engine and session factory.
+
+        Args:
+            engine (Optional[Engine]): The database engine to use.
+            session_factory (Optional[Callable[[], Session]]): A callable that provides new sessions.
+        """
+        config = load_config()
+        sql_db_url = db_url or config.SQL_DB_URL
+
+        # Ensure sqlite parent directory exists before engine creation
+        _ensure_sqlite_parent_dir(sql_db_url)
+
+        self.engine: Engine = engine or create_engine(sql_db_url, echo=False)
+        self.session_factory: Callable[[], Session] = session_factory or sessionmaker(
+            autocommit=False, autoflush=False, bind=self.engine
+        )
+
+    def get_engine(self) -> Engine:
+        """Return the configured database engine."""
+        return self.engine
+
+    def get_session_factory(self) -> Callable[[], Session]:
+        """Return the configured session factory."""
+        return self.session_factory
+
+    def get_db_session(self) -> Session:
+        """
+        Provide a new database session.
+
+        Returns:
+            Session: A new SQLAlchemy session.
+        """
+        return self.session_factory()
+
+    @contextmanager
+    def db_session_scope(self) -> Iterator[Session]:
+        """
+        Provide a transactional scope for database operations.
+
+        Yields:
+            Session: A transactional database session.
+        """
+        db_session = self.get_db_session()
+        try:
+            yield db_session
+            db_session.commit()
+        except Exception:
+            db_session.rollback()
+            raise
+        finally:
+            db_session.close()
+
+    def init_db(self) -> bool:
+        """Initialize the database schema."""
+        try:
+            logging.info("Initializing database schema...")
+            Base.metadata.create_all(bind=self.engine)
+            logging.info(f"Tables created: {Base.metadata.tables.keys()}")
+            return True
+        except Exception as e:
+            logging.error(f"Failed to initialize database schema: {e}")
+            return False
+
+    def drop_db(self) -> bool:
+        """Drop all tables in the database."""
+        try:
+            logging.info("Dropping all tables in the database...")
+            Base.metadata.drop_all(bind=self.engine)
+            logging.info("All tables dropped successfully.")
+            return True
+        except Exception as e:
+            logging.error(f"Failed to drop database: {e}")
+            return False
+
+    def check_db_connection(self) -> bool:
+        """Check if the database connection is active."""
+        try:
+            with self.engine.connect() as connection:
+                connection.execute(text("SELECT 1"))
+                logging.info("Database connection is active.")
+                return True
+        except Exception as e:
+            logging.error(f"Database connection check failed: {e}")
+            return False
+
+
+def _ensure_sqlite_parent_dir(sql_db_url: str) -> None:
+    """
+    Ensure the parent directory exists for sqlite database URLs.
+
+    Only applies to absolute-path sqlite URLs of the form:
+        sqlite:////absolute/path/to/db.sqlite
+
+    Relative sqlite paths are intentionally not supported as defaults.
+    """
+    prefix = "sqlite:///"
+    if not sql_db_url.startswith(prefix):
+        return
+
+    raw_path = sql_db_url[len(prefix) :]
+    if not raw_path:
+        return
+
+    db_path = Path(raw_path)
+
+    # Only create directories for absolute paths
+    if db_path.is_absolute():
+        db_path.parent.mkdir(parents=True, exist_ok=True)

mxm/refdata/mappings/__init__.py

@@ -0,0 +1,31 @@
+from mxm.refdata.mappings.futures_contract_vs_orm import (
+    futures_contract_from_orm,
+    futures_contract_to_orm,
+)
+from mxm.refdata.mappings.futures_product_vs_orm import (
+    futures_product_from_orm,
+    futures_product_to_orm,
+)
+from mxm.refdata.mappings.period_cycles_vs_orm import (
+    period_cycle_from_orm,
+    period_cycle_membership_from_orm,
+    period_cycle_membership_to_orm,
+    period_cycle_to_orm,
+)
+from mxm.refdata.mappings.period_vs_orm import (
+    period_from_orm,
+    period_to_orm,
+)
+
+__all__ = [
+    "futures_contract_from_orm",
+    "futures_contract_to_orm",
+    "futures_product_from_orm",
+    "futures_product_to_orm",
+    "period_cycle_from_orm",
+    "period_cycle_membership_from_orm",
+    "period_cycle_membership_to_orm",
+    "period_cycle_to_orm",
+    "period_from_orm",
+    "period_to_orm",
+]

mxm/refdata/mappings/futures_contract_vs_orm.py

@@ -0,0 +1,51 @@
+"""Mapping FuturesContract instances to and from FuturesContractORM instances."""
+
+from mxm.refdata.models.contracts.futures_contract import FuturesContract
+from mxm.refdata.models.orm import FuturesContractORM
+from mxm.refdata.models.products.futures_product import Currency, ProductUnit
+
+
+def futures_contract_to_orm(contract: FuturesContract) -> FuturesContractORM:
+    """
+    Map a FuturesContract object to a FuturesContractORM instance.
+
+    Args:
+        contract (FuturesContract): The internal FuturesContract object.
+
+    Returns:
+        FuturesContractORM: The corresponding ORM instance.
+    """
+    return FuturesContractORM(
+        contract_id=contract.contract_id,
+        product_id=contract.product_id,
+        period_id=contract.period_id,
+        contract_size=contract.contract_size,
+        unit=contract.unit,
+        currency=contract.currency,
+        trading_calendar=contract.trading_calendar,
+        first_day_of_interest=contract.first_day_of_interest,
+        last_trading_day=contract.last_trading_day,
+    )
+
+
+def futures_contract_from_orm(orm: FuturesContractORM) -> FuturesContract:
+    """
+    Map a FuturesContractORM object to a FuturesContract object.
+
+    Args:
+        orm (FuturesContractORM): The ORM object to map from.
+
+    Returns:
+        FuturesContract: The mapped internal representation.
+    """
+    return FuturesContract(
+        product_id=orm.product_id,  # Directly use product_id
+        period_id=orm.period_id,  # Directly use period_id
+        contract_id=orm.contract_id,
+        contract_size=orm.contract_size,
+        currency=Currency[orm.currency.name],  # Map string to Currency Enum
+        unit=ProductUnit[orm.unit.name],  # Map string to ProductUnit Enum
+        trading_calendar=orm.trading_calendar,
+        first_day_of_interest=orm.first_day_of_interest,
+        last_trading_day=orm.last_trading_day,
+    )

mxm/refdata/mappings/futures_product_vs_orm.py

@@ -0,0 +1,56 @@
+"""Mapping FututesProduct instances to and from FuturesProductORM instances."""
+
+from mxm.refdata.models.orm import FuturesProductORM
+from mxm.refdata.models.products.futures_product import FuturesProduct
+from mxm.refdata.utils.period_types_codec import (
+    decode_period_types,
+    encode_period_types,
+)
+
+
+def futures_product_to_orm(product: FuturesProduct) -> FuturesProductORM:
+    """Map a FuturesProduct to a FuturesProductORM instance."""
+    return FuturesProductORM(
+        product_id=product.product_id,
+        venue=product.venue,
+        description=product.description,
+        currency=product.currency,
+        unit=product.unit,
+        contract_size=product.contract_size,
+        valid_period_rule=product.valid_period_rule,
+        listing_rule=product.listing_rule,
+        period_types=encode_period_types(product.period_types),
+        settlement=product.settlement,
+        last_trading_rule=product.last_trading_rule,
+        expiry_rule=product.expiry_rule,
+        trading_calendar=product.trading_calendar,
+        trading_hours=product.trading_hours,
+        tick_size=product.tick_size,
+        tick_value=product.tick_value,
+        initial_margin=product.initial_margin,
+        maintenance_margin=product.maintenance_margin,
+    )
+
+
+def futures_product_from_orm(orm_instance: FuturesProductORM) -> FuturesProduct:
+    """Map a FuturesProductORM instance to a FuturesProduct."""
+    return FuturesProduct(
+        product_id=orm_instance.product_id,
+        venue=orm_instance.venue,
+        description=orm_instance.description,
+        currency=orm_instance.currency,
+        unit=orm_instance.unit,
+        contract_size=orm_instance.contract_size,
+        valid_period_rule=orm_instance.valid_period_rule,
+        listing_rule=orm_instance.listing_rule,
+        period_types=decode_period_types(orm_instance.period_types),
+        settlement=orm_instance.settlement,
+        last_trading_rule=orm_instance.last_trading_rule,
+        expiry_rule=orm_instance.expiry_rule,
+        trading_calendar=orm_instance.trading_calendar,
+        trading_hours=orm_instance.trading_hours,
+        tick_size=orm_instance.tick_size,
+        tick_value=orm_instance.tick_value,
+        initial_margin=orm_instance.initial_margin,
+        maintenance_margin=orm_instance.maintenance_margin,
+    )