mxm-refdata 0.3.0__py3-none-any.whl

mxm/refdata/mappings/period_cycles_vs_orm.py

@@ -0,0 +1,102 @@
+"""
+mxm.refdata.mappings.period_cycles_vs_orm
+
+ORM ↔ domain mappings for PeriodCycle and PeriodCycleMembership.
+
+Purpose
+-------
+`mxm-refdata` stores Period cycles as authoritative reference-data artifacts.
+A PeriodCycle is a definition of a cycle over delivery periods, and a
+PeriodCycleMembership places a specific Period into a given cycle with a
+(cycle_instance, cycle_element) assignment.
+
+This module provides the pure mapping functions between:
+- ORM models in `mxm.refdata.models.orm.period_cycles`
+and
+- domain models in `mxm.refdata.models.period_cycles`
+
+Conventions
+-----------
+- Enums are stored in the database as strings.
+- PeriodType is stored as `PeriodType.name` (e.g. "MONTH", "QUARTER").
+- CycleInstanceKind is stored as its `.value` (e.g. "YEAR").
+
+These conventions should be kept stable to preserve refdata portability and
+auditability.
+"""
+
+from __future__ import annotations
+
+from mxm.refdata.models.orm.period_cycles import (
+    PeriodCycleMembershipORM,
+    PeriodCycleORM,
+)
+from mxm.refdata.models.period_cycles import (
+    CycleInstanceKind,
+    PeriodCycle,
+    PeriodCycleMembership,
+)
+from mxm.refdata.models.periods import PeriodType
+
+# ---------------------------------------------------------------------------
+# PeriodCycle
+# ---------------------------------------------------------------------------
+
+
+def period_cycle_from_orm(orm: PeriodCycleORM) -> PeriodCycle:
+    """
+    Map ORM -> domain PeriodCycle.
+    """
+    return PeriodCycle(
+        cycle_id=orm.cycle_id,
+        name=orm.name,
+        period_type=PeriodType[orm.period_type],  # stored as PeriodType.name
+        cycle_size=int(orm.cycle_size),
+        instance_kind=CycleInstanceKind(orm.instance_kind),  # stored as .value
+    )
+
+
+def period_cycle_to_orm(model: PeriodCycle) -> PeriodCycleORM:
+    """
+    Map domain -> ORM PeriodCycleORM.
+    """
+    return PeriodCycleORM(
+        cycle_id=model.cycle_id,
+        name=model.name,
+        period_type=model.period_type.name,  # store as PeriodType.name
+        instance_kind=model.instance_kind.value,  # store as .value
+        cycle_size=int(model.cycle_size),
+    )
+
+
+# ---------------------------------------------------------------------------
+# PeriodCycleMembership
+# ---------------------------------------------------------------------------
+
+
+def period_cycle_membership_from_orm(
+    orm: PeriodCycleMembershipORM,
+) -> PeriodCycleMembership:
+    """
+    Map ORM -> domain PeriodCycleMembership.
+    """
+    return PeriodCycleMembership(
+        cycle_id=orm.cycle_id,
+        period_id=orm.period_id,
+        cycle_instance=int(orm.cycle_instance),
+        cycle_element=int(orm.cycle_element),
+    )
+
+
+def period_cycle_membership_to_orm(
+    model: PeriodCycleMembership,
+) -> PeriodCycleMembershipORM:
+    """
+    Map domain -> ORM PeriodCycleMembershipORM.
+    """
+    return PeriodCycleMembershipORM(
+        cycle_id=model.cycle_id,
+        period_id=model.period_id,
+        cycle_instance=int(model.cycle_instance),
+        cycle_element=int(model.cycle_element),
+    )

mxm/refdata/mappings/period_vs_orm.py

@@ -0,0 +1,40 @@
+"""Mapping Period instances to and from PeriodORM instances."""
+
+from mxm.refdata.models.orm.periods import PeriodORM
+from mxm.refdata.models.periods import Period, PeriodType
+
+
+def period_to_orm(period: Period) -> PeriodORM:
+    """
+    Map an internal Period object to a PeriodORM instance.
+
+    Args:
+        period (Period): Internal Period instance.
+
+    Returns:
+        PeriodORM: Corresponding ORM representation.
+    """
+    return PeriodORM(
+        period_id=period.period_id,
+        period_type=period.period_type,
+        first_date=period.first_date,
+        last_date=period.last_date,
+    )
+
+
+def period_from_orm(orm: PeriodORM) -> Period:
+    """
+    Map a PeriodORM instance to an internal Period object.
+
+    Args:
+        orm (PeriodORM): ORM representation of a Period.
+
+    Returns:
+        Period: Internal representation of the Period.
+    """
+    return Period(
+        period_id=orm.period_id,
+        period_type=PeriodType[orm.period_type.name],
+        first_date=orm.first_date,
+        last_date=orm.last_date,
+    )

mxm/refdata/models/__init__.py

@@ -0,0 +1,31 @@
+"""Internal Data Models and ORM for the reference data service."""
+
+from .contracts.futures_contract import FuturesContract
+from .currencies import Currency
+from .months import Month
+from .orm.base import Base
+from .orm.futures_contracts import FuturesContractORM
+from .orm.futures_products import FuturesProductORM
+from .orm.periods import PeriodORM
+from .periods import Period, PeriodType
+from .products.futures_product import FuturesProduct, SettlementMethod
+from .reference_events import ReferenceEvent
+from .units import ProductUnit
+from .weekdays import Weekday
+
+__all__ = [
+    "Base",
+    "Currency",
+    "FuturesContract",
+    "FuturesContractORM",
+    "FuturesProduct",
+    "FuturesProductORM",
+    "Month",
+    "Period",
+    "PeriodORM",
+    "PeriodType",
+    "ProductUnit",
+    "ReferenceEvent",
+    "SettlementMethod",
+    "Weekday",
+]

mxm/refdata/models/contracts/futures_contract.py

@@ -0,0 +1,22 @@
+"""Future contract class."""
+
+import datetime
+from dataclasses import dataclass
+
+from mxm.refdata.models.currencies import Currency
+from mxm.refdata.models.units import ProductUnit
+
+
+@dataclass(frozen=True)
+class FuturesContract:
+    """Represents an individual futures contract."""
+
+    contract_id: str  # Unique identifier for the contract
+    product_id: str  # Reference to the product ID
+    period_id: str  # Reference to the period ID
+    contract_size: float  # The specific size of this contract
+    unit: ProductUnit  # Pre-populated unit of the product
+    currency: Currency  # Pre-populated currency of the product
+    trading_calendar: str  # Pre-populated trading calendar of the product
+    first_day_of_interest: datetime.date  # The first day of interest for the contract
+    last_trading_day: datetime.date  # The last trading day for the contract

mxm/refdata/models/currencies.py

@@ -0,0 +1,24 @@
+"""This module defines the Currency Enum for ISO 4217 currency codes."""
+
+from enum import Enum
+
+
+class Currency(Enum):
+    """Currency Enum for ISO 4217 currency codes."""
+
+    AUD = "Australian Dollar"
+    CAD = "Canadian Dollar"
+    CHF = "Swiss Franc"
+    EUR = "Euro"
+    GBP = "Pound Sterling"
+    HKD = "Hong Kong Dollar"
+    INR = "Indian Rupee"
+    JPY = "Yen"
+    MXN = "Mexican Peso"
+    NOK = "Norwegian Krone"
+    NZD = "New Zealand Dollar"
+    SEK = "Swedish Krona"
+    SGD = "Singapore Dollar"
+    USD = "US Dollar"
+    BRL = "Brazilian Real"
+    CNY = "Yuan Renminbi"

mxm/refdata/models/months.py

@@ -0,0 +1,72 @@
+"""A data-class encapsulating calendar months and different representations."""
+
+from dataclasses import dataclass
+
+CME_MONTH_CODES = {
+    1: "F",
+    2: "G",
+    3: "H",
+    4: "J",
+    5: "K",
+    6: "M",
+    7: "N",
+    8: "Q",
+    9: "U",
+    10: "V",
+    11: "X",
+    12: "Z",
+}
+
+MONTH_STRINGS = {
+    1: "Jan",
+    2: "Feb",
+    3: "Mar",
+    4: "Apr",
+    5: "May",
+    6: "Jun",
+    7: "Jul",
+    8: "Aug",
+    9: "Sep",
+    10: "Oct",
+    11: "Nov",
+    12: "Dec",
+}
+
+MONTH_STRINGS_REVERSE = {v: k for k, v in MONTH_STRINGS.items()}
+
+
+@dataclass(frozen=True)
+class Month:
+    """Represents a month with various representations."""
+
+    month: int  # 1 (January) to 12 (December)
+
+    def __post_init__(self):
+        if not (1 <= self.month <= 12):
+            raise ValueError(f"Invalid month: {self.month}. Must be between 1 and 12.")
+
+    @property
+    def as_int(self) -> int:
+        """Return the month as an integer."""
+        return self.month
+
+    @property
+    def as_str(self) -> str:
+        """Return the month as a three-letter abbreviation."""
+        return MONTH_STRINGS[self.month]
+
+    @property
+    def as_cme_code(self) -> str:
+        """Return the month as a CME code."""
+        return CME_MONTH_CODES[self.month]
+
+    @classmethod
+    def from_str(cls, month_str: str) -> "Month":
+        """Create a Month instance from a three-letter abbreviation."""
+        month_int = MONTH_STRINGS_REVERSE.get(month_str)
+        if not month_int:
+            raise ValueError(
+                f"Invalid month abbreviation: {month_str}. "
+                f"Expected one of {list(MONTH_STRINGS_REVERSE.keys())}."
+            )
+        return cls(month_int)

mxm/refdata/models/orm/__init__.py

@@ -0,0 +1,16 @@
+"""ORM models for DB integration."""
+
+from .base import Base
+from .futures_contracts import FuturesContractORM
+from .futures_products import FuturesProductORM
+from .period_cycles import PeriodCycleMembershipORM, PeriodCycleORM
+from .periods import PeriodORM
+
+__all__ = [
+    "Base",
+    "FuturesContractORM",
+    "FuturesProductORM",
+    "PeriodCycleMembershipORM",
+    "PeriodCycleORM",
+    "PeriodORM",
+]

mxm/refdata/models/orm/base.py

@@ -0,0 +1,3 @@
+from sqlalchemy.orm import declarative_base
+
+Base = declarative_base()

mxm/refdata/models/orm/futures_contracts.py

@@ -0,0 +1,53 @@
+"""
+ORM model for the futures_contracts table.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Date, Enum, Float, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from mxm.refdata.models.orm.base import Base
+from mxm.refdata.models.products.futures_product import Currency, ProductUnit
+
+if TYPE_CHECKING:
+    from mxm.refdata.models.orm.futures_products import FuturesProductORM
+    from mxm.refdata.models.orm.periods import PeriodORM
+
+
+class FuturesContractORM(Base):
+    """ORM model for the futures_contracts table."""
+
+    __tablename__ = "futures_contracts"
+
+    contract_id: Mapped[str] = mapped_column(String, primary_key=True, nullable=False)
+
+    product_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("futures_products.product_id"),
+        nullable=False,
+    )
+
+    period_id: Mapped[str] = mapped_column(
+        String,
+        ForeignKey("periods.period_id"),
+        nullable=False,
+    )
+
+    contract_size: Mapped[float] = mapped_column(Float, nullable=False)
+    currency: Mapped[Currency] = mapped_column(Enum(Currency), nullable=False)
+    unit: Mapped[ProductUnit] = mapped_column(Enum(ProductUnit), nullable=False)
+
+    trading_calendar: Mapped[str] = mapped_column(String, nullable=False)
+
+    first_day_of_interest: Mapped[date] = mapped_column(Date, nullable=False)
+    last_trading_day: Mapped[date] = mapped_column(Date, nullable=False)
+
+    # Relationships
+    product: Mapped[FuturesProductORM] = relationship(
+        "FuturesProductORM", back_populates="contracts"
+    )
+    period: Mapped[PeriodORM] = relationship("PeriodORM", back_populates="contracts")

mxm/refdata/models/orm/futures_products.py

@@ -0,0 +1,61 @@
+"""
+ORM model for the futures_products table.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Enum, Float, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from mxm.refdata.models.orm.base import Base
+from mxm.refdata.models.products.futures_product import (
+    Currency,
+    ProductUnit,
+    SettlementMethod,
+)
+
+if TYPE_CHECKING:
+    from mxm.refdata.models.orm.futures_contracts import FuturesContractORM
+
+
+class FuturesProductORM(Base):
+    """ORM model for the futures_products table."""
+
+    __tablename__ = "futures_products"
+
+    product_id: Mapped[str] = mapped_column(String, primary_key=True, nullable=False)
+    venue: Mapped[str] = mapped_column(String, nullable=False)
+    description: Mapped[str] = mapped_column(Text, nullable=False)
+
+    currency: Mapped[Currency] = mapped_column(Enum(Currency), nullable=False)
+    unit: Mapped[ProductUnit] = mapped_column(Enum(ProductUnit), nullable=False)
+    contract_size: Mapped[float] = mapped_column(Float, nullable=False)
+
+    valid_period_rule: Mapped[str] = mapped_column(Text, nullable=False)
+    listing_rule: Mapped[str] = mapped_column(Text, nullable=False)
+
+    period_types: Mapped[str] = mapped_column(Text, nullable=False)
+
+    settlement: Mapped[SettlementMethod] = mapped_column(
+        Enum(SettlementMethod), nullable=False
+    )
+    last_trading_rule: Mapped[str] = mapped_column(Text, nullable=False)
+    expiry_rule: Mapped[str] = mapped_column(Text, nullable=False)
+
+    trading_calendar: Mapped[str] = mapped_column(String, nullable=False)
+
+    trading_hours: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    tick_size: Mapped[float | None] = mapped_column(Float, nullable=True)
+    tick_value: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+    initial_margin: Mapped[float | None] = mapped_column(Float, nullable=True)
+    maintenance_margin: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+    contracts: Mapped[list[FuturesContractORM]] = relationship(
+        "FuturesContractORM",
+        back_populates="product",
+        cascade="all, delete-orphan",
+    )

mxm/refdata/models/orm/period_cycles.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from sqlalchemy import ForeignKey, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from mxm.refdata.models.orm.base import Base
+from mxm.refdata.models.orm.periods import PeriodORM
+
+
+class PeriodCycleORM(Base):
+    __tablename__ = "period_cycles"
+
+    cycle_id: Mapped[str] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(nullable=False)
+    period_type: Mapped[str] = mapped_column(nullable=False)
+    instance_kind: Mapped[str] = mapped_column(nullable=False)
+    cycle_size: Mapped[int] = mapped_column(nullable=False)
+
+    # Relationship: one cycle -> many memberships
+    memberships = relationship(
+        "PeriodCycleMembershipORM",
+        back_populates="cycle",
+        cascade="all, delete-orphan",
+        lazy="select",
+    )
+
+    def __repr__(self) -> str:
+        return (
+            f"PeriodCycleORM(cycle_id={self.cycle_id!r}, name={self.name!r}, "
+            f"period_type={self.period_type!r}, instance_kind={self.instance_kind!r}, "
+            f"cycle_size={self.cycle_size!r})"
+        )
+
+
+class PeriodCycleMembershipORM(Base):
+    """
+    ORM table: period_cycle_memberships
+
+    Membership relation: places a specific Period into a given PeriodCycle.
+    """
+
+    __tablename__ = "period_cycle_memberships"
+
+    # Composite primary key: one period per cycle
+    cycle_id: Mapped[str] = mapped_column(
+        ForeignKey("period_cycles.cycle_id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+
+    period_id: Mapped[str] = mapped_column(
+        ForeignKey("periods.period_id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+
+    cycle_instance: Mapped[int] = mapped_column(nullable=False)
+    cycle_element: Mapped[int] = mapped_column(nullable=False)
+
+    # Relationships
+    cycle: Mapped[PeriodCycleORM] = relationship(
+        back_populates="memberships",
+        lazy="select",
+    )
+
+    period: Mapped[PeriodORM] = relationship(
+        lazy="select",
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "cycle_id",
+            "cycle_instance",
+            "cycle_element",
+            name="uq_cycle_instance_element",
+        ),
+    )
+
+    def __repr__(self) -> str:
+        return (
+            "PeriodCycleMembershipORM("
+            f"cycle_id={self.cycle_id!r}, "
+            f"period_id={self.period_id!r}, "
+            f"cycle_instance={self.cycle_instance!r}, "
+            f"cycle_element={self.cycle_element!r})"
+        )

mxm/refdata/models/orm/periods.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from datetime import date
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Date, Enum, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from mxm.refdata.models.orm.base import Base
+from mxm.refdata.models.periods import PeriodType
+
+if TYPE_CHECKING:
+    from mxm.refdata.models.orm.futures_contracts import FuturesContractORM
+
+
+class PeriodORM(Base):
+    """ORM model for the periods table."""
+
+    __tablename__ = "periods"
+
+    period_id: Mapped[str] = mapped_column(
+        String, primary_key=True, unique=True, nullable=False
+    )
+    period_type: Mapped[PeriodType] = mapped_column(Enum(PeriodType), nullable=False)
+    first_date: Mapped[date] = mapped_column(Date, nullable=False)
+    last_date: Mapped[date] = mapped_column(Date, nullable=False)
+
+    contracts: Mapped[list[FuturesContractORM]] = relationship(
+        "FuturesContractORM", back_populates="period"
+    )

mxm/refdata/models/period_cycles.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from mxm.refdata.models.periods import PeriodType
+
+
+class CycleInstanceKind(str, Enum):
+    """
+    Defines what 'cycle_instance' means for a membership row.
+
+    For calendar cycles, the instance is the calendar year.
+    Other instance kinds may be added later (e.g. gas_year).
+    """
+
+    YEAR = "YEAR"
+
+
+@dataclass(frozen=True)
+class PeriodCycle:
+    """
+    Defines a cycle over periods.
+
+    A cycle is an interpretation layer over Periods, not a property of Period itself.
+
+    Example cycles:
+    - CALENDAR_MONTHS: element=1..12, instance=year, applies to PeriodType.MONTH
+    - CALENDAR_QUARTERS: element=1..4, instance=year, applies to PeriodType.QUARTER
+    """
+
+    cycle_id: str  # stable identifier, e.g. "CALENDAR_MONTHS"
+    name: str  # human readable
+    period_type: PeriodType  # the period type this cycle classifies
+    cycle_size: int  # number of elements in one cycle (12, 4, ...)
+    instance_kind: CycleInstanceKind = CycleInstanceKind.YEAR
+
+    def __post_init__(self) -> None:
+        if not self.cycle_id:
+            raise ValueError("cycle_id must be non-empty")
+        if not self.name:
+            raise ValueError("name must be non-empty")
+        if self.cycle_size < 1:
+            raise ValueError("cycle_size must be >= 1")
+
+
+@dataclass(frozen=True)
+class PeriodCycleMembership:
+    """
+    Membership relation: places a specific Period into a given cycle.
+
+    A Period may be a member of multiple cycles.
+    A cycle may contain many periods.
+
+    cycle_instance:
+        For YEAR instance_kind cycles, this is the calendar year.
+        (Other instance kinds may be introduced later.)
+    """
+
+    cycle_id: str
+    period_id: str
+    cycle_instance: int
+    cycle_element: int  # 1..cycle_size
+
+    def __post_init__(self) -> None:
+        if not self.cycle_id:
+            raise ValueError("cycle_id must be non-empty")
+        if not self.period_id:
+            raise ValueError("period_id must be non-empty")
+        if self.cycle_instance <= 0:
+            raise ValueError("cycle_instance must be > 0")
+        if self.cycle_element < 1:
+            raise ValueError("cycle_element must be >= 1")

mxm/refdata/models/periods.py

@@ -0,0 +1,64 @@
+"""Reference periods for futures contracts."""
+
+from dataclasses import dataclass
+from datetime import date
+from enum import Enum
+from functools import total_ordering
+
+import pandas as pd
+
+
+class PeriodType(Enum):
+    """Period types for futures contracts."""
+
+    YEAR = "year"
+    QUARTER = "quarter"
+    MONTH = "month"
+    WEEK = "week"
+    DAY = "day"
+
+
+PERIOD_PRIORITY = {
+    PeriodType.YEAR: 1,
+    PeriodType.QUARTER: 2,
+    PeriodType.MONTH: 3,
+    PeriodType.WEEK: 4,
+    PeriodType.DAY: 5,
+}
+
+
+@total_ordering
+@dataclass(frozen=True)
+class Period:
+    """Represents a specific calendar period."""
+
+    period_id: (
+        str  # A unique identifier, like "2024", "Jan-2024", "2024-Q1", or "2024-W24"
+    )
+    period_type: PeriodType  # The type of the period (year, month, quarter, week)
+    first_date: date  # The first day of the period
+    last_date: date  # The last day of the period
+
+    def __post_init__(self):
+        if self.first_date > self.last_date:
+            raise ValueError("first_date must not be after last_date")
+
+    def __str__(self):
+        return f"{self.period_type.name} Period: {self.period_id} ({self.first_date} to {self.last_date})"
+
+    def __repr__(self):
+        return f"Period(period_id='{self.period_id}', period_type={self.period_type}, first_date={self.first_date}, last_date={self.last_date})"
+
+    def __lt__(self, other: "Period") -> bool:
+        """Define sorting: higher-level periods (Year > Month) first, then by start date."""
+
+        if PERIOD_PRIORITY[self.period_type] != PERIOD_PRIORITY[other.period_type]:
+            return (
+                PERIOD_PRIORITY[self.period_type] < PERIOD_PRIORITY[other.period_type]
+            )
+
+        return self.first_date < other.first_date
+
+    def to_daterange(self) -> pd.DatetimeIndex:
+        """Return a pandas date_range from first_date to last_date, with daily frequency."""
+        return pd.date_range(self.first_date, self.last_date, freq="D")

mxm/refdata/models/products/__init__.py

@@ -0,0 +1 @@
+"""Models for financial products."""