mxm-refdata 0.3.0__py3-none-any.whl

mxm/refdata/trading_calendars/first_day_of_interest.py

@@ -0,0 +1,74 @@
+"""Calculate the first day we are interested in a given FuturesContract."""
+
+import json
+from datetime import date
+from importlib.resources import files
+
+from mxm.refdata.models import Period, PeriodType
+from mxm.refdata.services.period_factory import PeriodFactory
+from mxm.refdata.trading_calendars.last_trading_day import calculate_last_trading_day
+from mxm.refdata.trading_calendars.trading_calendar import TradingCalendar
+
+# Load first_day_of_interest rules from JSON file
+FIRST_DAY_OF_INTEREST_RULES = json.loads(
+    files("mxm.refdata")
+    .joinpath("data/first_day_of_interest_rule.json")
+    .read_text(encoding="utf-8")
+)
+
+
+def calculate_first_day_of_interest(
+    product_id: str, period: Period, trading_calendar: TradingCalendar
+) -> date:
+    """
+    Calculate the first_day_of_interest for a given futures contract.
+
+    Parameters:
+    - product_id (str): The product identifier for the futures contract.
+    - period (Period): The period representing the contract's expiration/delivery period.
+    - trading_calendar (TradingCalendar): The trading calendar to use for business day calculations.
+
+    Returns:
+    - date: The first business day we are interested in a given FuturesContract.
+
+    Raises:
+    - ValueError: If the product_id is not found in the JSON rules.
+    - ValueError: If period_type is not MONTH.
+    """
+    if product_id not in FIRST_DAY_OF_INTEREST_RULES:
+        raise ValueError(
+            f"No first_day_of_interest rule found for product_id: {product_id}"
+        )
+
+    if period.period_type != PeriodType.MONTH:
+        raise ValueError(f"Unsupported period_type: {period.period_type}")
+
+    product_rules = FIRST_DAY_OF_INTEREST_RULES[product_id]
+    month_str = period.first_date.strftime("%b")
+    try:
+        shift_n = product_rules["shift_rule"]["n_shift"][month_str]
+    except KeyError as e:
+        raise KeyError(
+            f"No shift value found for month '{month_str}' in product_id: {product_id}"
+        ) from e
+
+    shifted_period = PeriodFactory().shift_period_by_n(period, n=-shift_n)
+
+    # Determine reference date based on reference rule
+    reference_rule = product_rules["reference_rule"]
+
+    if reference_rule == "next_b_day_after_last_trading_day_of_december":
+        december_period = PeriodFactory.get_period(
+            date_obj=date(shifted_period.last_date.year, 12, 1),
+            period_type=PeriodType.MONTH,
+        )
+
+        reference_date = calculate_last_trading_day(
+            product_id, december_period, trading_calendar
+        )
+    elif reference_rule == "next_b_day_after_period":
+        reference_date = shifted_period.last_date
+    else:
+        raise ValueError(f"Unsupported reference_rule: {reference_rule}")
+
+    return trading_calendar.get_nth_business_day_relative_to_date(reference_date, n=1)

mxm/refdata/trading_calendars/last_trading_day.py

@@ -0,0 +1,117 @@
+import datetime
+import json
+from importlib.resources import files
+from typing import NotRequired, TypedDict, cast
+
+from mxm.refdata.models.periods import Period
+from mxm.refdata.models.reference_events import ReferenceEvent
+from mxm.refdata.models.weekdays import Weekday
+from mxm.refdata.services.period_factory import PeriodFactory
+from mxm.refdata.trading_calendars.nth_business_day import (
+    get_nth_business_day_of_period,
+)
+from mxm.refdata.trading_calendars.nth_calendar_day_of_period import (
+    get_nth_calendar_day_of_period,
+)
+from mxm.refdata.trading_calendars.nth_weekday_of_period import (
+    get_nth_weekday_of_period,
+)
+from mxm.refdata.trading_calendars.trading_calendar import TradingCalendar
+
+
+class LastTradingRule(TypedDict):
+    period_offset: int
+    reference_event: str
+    n_reference: int
+    business_day_offset: int
+    weekday: NotRequired[str]
+
+
+type LastTradingRules = dict[str, LastTradingRule]
+
+TRADING_RULES: LastTradingRules = cast(
+    LastTradingRules,
+    json.loads(
+        files("mxm.refdata")
+        .joinpath("data/last_trading_rule.json")
+        .read_text(encoding="utf-8")
+    ),
+)
+
+
+def get_reference_date(
+    *,
+    product_id: str,
+    adjusted_period: Period,
+    rule: LastTradingRule,
+    trading_calendar: TradingCalendar,
+) -> datetime.date:
+    """Resolve the reference date specified by a product last-trading-day rule."""
+    reference_event = ReferenceEvent(rule["reference_event"])
+    n_reference = int(rule["n_reference"])
+
+    match reference_event:
+        case ReferenceEvent.BUSINESS_DAY_OF_PERIOD:
+            return get_nth_business_day_of_period(
+                adjusted_period,
+                n_reference,
+                trading_calendar,
+            )
+
+        case ReferenceEvent.CALENDAR_DAY_OF_PERIOD:
+            return get_nth_calendar_day_of_period(
+                adjusted_period,
+                n_reference,
+            )
+
+        case ReferenceEvent.WEEKDAY_OF_PERIOD:
+            weekday_raw = rule.get("weekday")
+            if not isinstance(weekday_raw, str):
+                raise ValueError(
+                    f"Missing or invalid 'weekday' key in trading rule for {product_id}"
+                )
+
+            return get_nth_weekday_of_period(
+                adjusted_period,
+                Weekday.from_str(weekday_raw).as_int,
+                n_reference,
+            )
+
+        case _:
+            raise ValueError(f"Unsupported reference_event: {reference_event!r}")
+
+
+def calculate_last_trading_day(
+    product_id: str,
+    period: Period,
+    trading_calendar: TradingCalendar,
+) -> datetime.date:
+    """
+    Calculate the last trading day for a futures contract.
+
+    The calculation is based on the product-specific last-trading-day rule,
+    the contract period, and the relevant trading calendar.
+    """
+    if product_id not in TRADING_RULES:
+        raise KeyError(f"No trading rule found for product: {product_id}")
+
+    rule = TRADING_RULES[product_id]
+
+    adjusted_period = PeriodFactory.shift_period_by_n(
+        period,
+        int(rule["period_offset"]),
+    )
+
+    reference_date = get_reference_date(
+        product_id=product_id,
+        adjusted_period=adjusted_period,
+        rule=rule,
+        trading_calendar=trading_calendar,
+    )
+
+    business_day_offset = int(rule.get("business_day_offset", 0))
+
+    return trading_calendar.get_nth_business_day_relative_to_date(
+        reference_date,
+        business_day_offset,
+    )

mxm/refdata/trading_calendars/nth_business_day.py

@@ -0,0 +1,52 @@
+"""Calculate n-th business day of a period."""
+
+import datetime
+
+from mxm.refdata.models.periods import Period
+from mxm.refdata.trading_calendars.trading_calendar import TradingCalendar
+
+
+def get_nth_business_day_of_period(
+    period: Period, n: int, trading_calendar: TradingCalendar
+) -> datetime.date:
+    """
+    Returns the N-th business day of the given period.
+
+    Supports:
+      - **Positive `n` values** (e.g., `n=1` → First business day).
+      - **Negative `n` values** (e.g., `n=-1` → Last business day).
+
+    Args:
+        period (Period): The period (e.g., contract month, quarter).
+        n (int): The N-th business day (1-based index for forward search, -1-based for reverse search).
+        trading_calendar (TradingCalendar): The trading calendar to determine business days.
+
+    Returns:
+        datetime.date: The date of the N-th business day.
+
+    Raises:
+        ValueError: If the N-th business day does not exist in the period.
+
+    Examples:
+        - **Contract Month (June 2025)**:
+            - `get_nth_business_day_of_period(Period(2025, 6), 1, trading_calendar)` → First business day of June 2025.
+            - `get_nth_business_day_of_period(Period(2025, 6), -1, trading_calendar)` → Last business day of June 2025.
+
+        - **Quarter (Q3 2025)**:
+            - `get_nth_business_day_of_period(Period(2025, 7, 9), 5, trading_calendar)` → Fifth business day of Q3 2025.
+    """
+    all_dates = period.to_daterange()
+
+    # Get valid business days within the period
+    business_days = [
+        date
+        for date in trading_calendar.get_sessions_in_range(all_dates[0], all_dates[-1])
+    ]
+
+    # Ensure we return a date object, not a timestamp
+    try:
+        return business_days[n - 1].date() if n > 0 else business_days[n].date()
+    except IndexError as err:
+        raise ValueError(
+            f"The {n}-th business day does not exist in {period.period_id}."
+        ) from err

mxm/refdata/trading_calendars/nth_calendar_day_of_period.py

@@ -0,0 +1,43 @@
+import datetime
+
+from mxm.refdata.models.periods import Period
+
+
+def get_nth_calendar_day_of_period(period: Period, n: int) -> datetime.date:
+    """
+    Returns the N-th calendar day of the given period.
+
+    Supports:
+      - **Positive `n` values** (e.g., `n=1` → First day of the period).
+      - **Negative `n` values** (e.g., `n=-1` → Last day of the period).
+
+    Args:
+        period (Period): The period (e.g., contract month, quarter).
+        n (int): The N-th calendar day (1-based index for forward search, -1-based for reverse search).
+
+    Returns:
+        datetime.date: The date of the N-th calendar day.
+
+    Raises:
+        ValueError: If the N-th calendar day does not exist in the period.
+
+    Examples:
+        - **Contract Month (June 2025)**:
+            - `get_nth_calendar_day_of_period(Period(2025, 6), 1)` → June 1, 2025.
+            - `get_nth_calendar_day_of_period(Period(2025, 6), -1)` → June 30, 2025.
+
+        - **Quarter (Q3 2025)**:
+            - `get_nth_calendar_day_of_period(Period(2025, 7, 9), 5)` → July 5, 2025.
+            - `get_nth_calendar_day_of_period(Period(2025, 7, 9), -5)` → September 26, 2025.
+    """
+    all_days = period.to_daterange()
+
+    # Ensure valid index and return the correct day
+    try:
+        return (
+            all_days[n - 1].date() if n > 0 else all_days[n].date()
+        )  # Adjust for 1-based indexing
+    except IndexError as err:
+        raise ValueError(
+            f"The {n}-th calendar day does not exist in {period.period_id}."
+        ) from err

mxm/refdata/trading_calendars/nth_weekday_of_period.py

@@ -0,0 +1,50 @@
+"""Utility functions for working with calendars."""
+
+import datetime
+
+import pandas as pd
+
+from mxm.refdata.models.periods import Period
+from mxm.refdata.models.weekdays import Weekday
+
+
+def get_nth_weekday_of_period(
+    period: Period, weekday: int | str, n: int
+) -> datetime.date:
+    """
+    Returns the N-th occurrence of a given weekday in the specified period.
+
+    Supports:
+      - `weekday` as an **integer** (0=Monday, 6=Sunday).
+      - `weekday` as a **full name** ("Tuesday", "Friday").
+      - `weekday` as an **abbreviation** ("Tue", "Fri").
+
+    Args:
+        period (Period): The period (e.g., contract month, quarter).
+        weekday (int | str): The weekday (0=Monday, 6=Sunday or "Tuesday", "Tue", etc.).
+        n (int): The N-th occurrence (1-based index for forward search, -1-based for reverse search).
+
+    Returns:
+        datetime.date: The date of the N-th occurrence of the given weekday.
+
+    Raises:
+        ValueError: If the N-th occurrence does not exist in the period.
+    """
+    # Convert weekday string to integer if needed
+    if isinstance(weekday, str):
+        weekday = Weekday.from_str(weekday).as_int
+    period_range = period.to_daterange()
+    # Get all dates in the period and filter for matching weekdays
+    dates: list[pd.Timestamp] = [
+        date for date in period_range if date.weekday() == weekday
+    ]
+
+    # Handle both forward (n > 0) and reverse (n < 0) indexing
+    try:
+        return (
+            dates[n - 1].date() if n > 0 else dates[n].date()
+        )  # Python negative index works naturally
+    except IndexError as err:
+        raise ValueError(
+            f"The {n}-th occurrence of weekday {weekday} does not exist in {period.period_id}."
+        ) from err

mxm/refdata/trading_calendars/trading_calendar.py

@@ -0,0 +1,186 @@
+import datetime
+from typing import cast
+
+import exchange_calendars as xcals
+import pandas as pd
+from exchange_calendars.errors import InvalidCalendarName
+
+
+class TradingCalendar:
+    """
+    TradingCalendar manages exchange trading sessions and provides session-based utilities.
+    Sessions are represented by UTC Timestamps, following `exchange_calendars` conventions.
+    """
+
+    def __init__(
+        self,
+        calendar_name: str,
+        start: datetime.date | None = None,
+        end: datetime.date | None = None,
+    ):
+        """
+        Initializes a TradingCalendar based on an exchange calendar.
+
+        Args:
+            calendar_name (str): The name of the exchange calendar (e.g., "CMES", "NYSE").
+            extend_to (datetime.date, optional): Extend the calendar to this date if needed.
+
+        Raises:
+            ValueError: If the calendar name is not recognized by `exchange_calendars`.
+        """
+        try:
+            if start and not end:
+                self.calendar = xcals.get_calendar(calendar_name, start=start)
+            elif end and not start:
+                self.calendar = xcals.get_calendar(calendar_name, end=end)
+            elif start and end:
+                self.calendar = xcals.get_calendar(calendar_name, start=start, end=end)
+            else:
+                self.calendar = xcals.get_calendar(calendar_name)
+
+        except InvalidCalendarName as e:
+            raise ValueError(f"Unknown trading calendar: {calendar_name}") from e
+
+    def get_sessions_in_range(
+        self, start: datetime.date, end: datetime.date
+    ) -> pd.DatetimeIndex:
+        """
+        Returns trading sessions in a given range as a DatetimeIndex in UTC.
+
+        Args:
+            start (datetime.date): The start of the range.
+            end (datetime.date): The end of the range.
+
+        Returns:
+            pd.DatetimeIndex: A list of session timestamps in UTC.
+        """
+        return self.calendar.sessions_in_range(start, end)
+
+    def shift_sessions(self, session: pd.Timestamp, offset: int) -> pd.Timestamp:
+        """
+        Moves a given session forward or backward by a specified number of sessions.
+
+        Args:
+            session (pd.Timestamp): The session timestamp in UTC.
+            offset (int): Number of sessions to shift (+ for forward, - for backward).
+
+        Returns:
+            pd.Timestamp: The shifted session timestamp in UTC.
+        """
+        return self.calendar.session_offset(session, offset)
+
+    def get_session_dates_in_range(
+        self, start: datetime.date, end: datetime.date
+    ) -> list[datetime.date]:
+        """
+        Returns trading session dates in a given range.
+
+        Args:
+            start (datetime.date): The start date.
+            end (datetime.date): The end date.
+
+        Returns:
+            List[datetime.date]: A list of session dates.
+        """
+        return [ts.date() for ts in self.get_sessions_in_range(start, end)]
+
+    def shift_session_date(self, date: datetime.date, offset: int) -> datetime.date:
+        """
+        Moves a given date forward or backward by a specified number of trading sessions.
+
+        Args:
+            date (datetime.date): The reference date.
+            offset (int): Number of sessions to shift (+ for forward, - for backward).
+
+        Returns:
+            datetime.date: The shifted session's date.
+        """
+        return self.shift_sessions(pd.Timestamp(date), offset).date()
+
+    def get_session_open(self, session: pd.Timestamp) -> pd.Timestamp:
+        """
+        Returns the opening time of a given session.
+
+        Args:
+            session (pd.Timestamp): The session timestamp in UTC.
+
+        Returns:
+            pd.Timestamp: The market open time for the session (UTC).
+        """
+        return cast(pd.Timestamp, self.calendar.schedule.loc[session, "open"])
+
+    def get_session_close(self, session: pd.Timestamp) -> pd.Timestamp:
+        """
+        Returns the closing time of a given session.
+
+        Args:
+            session (pd.Timestamp): The session timestamp in UTC.
+
+        Returns:
+            pd.Timestamp: The market close time for the session (UTC).
+        """
+        return cast(pd.Timestamp, self.calendar.schedule.loc[session, "close"])
+
+    def is_trading_day(self, date: datetime.date) -> bool:
+        """
+        Checks if a given date is a valid trading day.
+
+        Args:
+            date (datetime.date): The date to check.
+
+        Returns:
+            bool: True if the date is a trading day, False otherwise.
+        """
+        return self.calendar.is_session(date)
+
+    def get_last_prior_session_date(self, date: datetime.date) -> datetime.date:
+        """
+        Finds the last valid session date prior to or on the given date.
+
+        Args:
+            date (datetime.date): The date to check.
+
+        Returns:
+            datetime.date: The last valid trading session date.
+
+        Raises:
+            ValueError: If the date is before the first available session in the trading calendar.
+        """
+        # If it's already a trading day, return it as is
+        if self.is_trading_day(date):
+            return date
+
+        # Start from the given date and move backward until we find a valid session
+        while not self.is_trading_day(date):
+            date -= datetime.timedelta(days=1)
+            if date < self.calendar.first_session.date():
+                raise ValueError(f"No prior session found for date {date}")
+
+        return date
+
+    def get_nth_business_day_relative_to_date(
+        self, date: datetime.date, n: int
+    ) -> datetime.date:
+        """
+        Finds the N-th business day relative to a given date, even if the date is not a business day.
+
+        If the date is not a business day:
+        - When `n < 0` (backward shift), we already moved back once, so shift by `n + 1`.
+        - When `n > 0` (forward shift), shift by `n` as usual.
+
+        Args:
+            date (datetime.date): The starting date (can be a business or non-business day).
+            n (int): The number of business days to move (+ for forward, - for backward).
+
+        Returns:
+            datetime.date: The computed business day.
+
+        """
+        # If the date is not a business day, find the last valid business day before it
+        if not self.is_trading_day(date):
+            date = self.get_last_prior_session_date(date)
+            if n < 0:
+                n += 1  # If moving backward, adjust by 1 because we already moved back
+
+        # Now shift by `n` business days from a valid business day
+        return self.shift_session_date(date, n)

mxm/refdata/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility functions for the refData package."""

mxm/refdata/utils/cache_manager.py

@@ -0,0 +1,33 @@
+"""A cache manager for the reference data service."""
+
+import threading
+
+from cachetools import LRUCache
+
+
+class CacheManager[V]:
+    """Thread-safe cache manager using an LRU cache."""
+
+    def __init__(self, maxsize: int = 1000) -> None:
+        self._cache: LRUCache[str, V] = LRUCache(maxsize=maxsize)
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> V | None:
+        """Thread-safe retrieval from the cache."""
+        with self._lock:
+            return self._cache.get(key)
+
+    def set(self, key: str, value: V) -> None:
+        """Thread-safe insertion into the cache."""
+        with self._lock:
+            self._cache[key] = value
+
+    def invalidate(self, key: str) -> None:
+        """Thread-safe removal from the cache."""
+        with self._lock:
+            self._cache.pop(key, None)
+
+    def clear(self) -> None:
+        """Thread-safe clearing of the cache."""
+        with self._lock:
+            self._cache.clear()

mxm/refdata/utils/config.py

@@ -0,0 +1,32 @@
+"""Configuration details for the refData application."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import ClassVar
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _default_sqlite_db_url() -> str:
+    # Stable, user-writable default (avoid process-relative paths)
+    db_path = Path.home() / ".mxm" / "refdata" / "refdata.db"
+    return f"sqlite:///{db_path}"
+
+
+class Config(BaseSettings):
+    # Overrideable via env; default is safe when imported as a dependency
+    SQL_DB_URL: str = _default_sqlite_db_url()
+
+    REFDATA_DB_MODE: str = "buildable"  # "buildable" | "managed"
+
+    # None means "use packaged CSV resource"
+    REFDATA_FUTURES_PRODUCTS_CSV_PATH: str | None = None
+
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8"
+    )
+
+
+def load_config() -> Config:
+    return Config()

mxm/refdata/utils/period_types_codec.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from mxm.refdata.models.periods import PeriodType
+
+
+def encode_period_types(values: tuple[PeriodType, ...]) -> str:
+    if not values:
+        raise ValueError("period_types must be non-empty")
+    return ",".join(v.name for v in values)
+
+
+def decode_period_types(value: str) -> tuple[PeriodType, ...]:
+    parts = [p.strip() for p in value.replace("|", ",").split(",") if p.strip()]
+    if not parts:
+        raise ValueError(f"invalid period_types string: {value!r}")
+    return tuple(PeriodType[p] for p in parts)

mxm/refdata/utils/regex_patterns.py

@@ -0,0 +1,18 @@
+"""Pre-computed regex patterns for use in the refData package."""
+
+import re
+from types import MappingProxyType
+
+from mxm.refdata.models.periods import PeriodType
+
+PERIOD_TYPE_PARSING_MAP = MappingProxyType(
+    {
+        PeriodType.YEAR: re.compile(r"^\d{4}$"),
+        PeriodType.MONTH: re.compile(
+            r"^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-\d{4}$"
+        ),
+        PeriodType.QUARTER: re.compile(r"^\d{4}-Q[1-4]$"),
+        PeriodType.WEEK: re.compile(r"^\d{4}-W\d{1,2}$"),
+        PeriodType.DAY: re.compile(r"^\d{4}\d{2}\d{2}$"),
+    }
+)

mxm/refdata/utils/resources.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from importlib.resources import as_file, files
+from pathlib import Path
+
+from mxm.refdata.utils.config import Config
+
+
+@contextmanager
+def futures_products_csv_path(cfg: Config) -> Iterator[Path]:
+    """
+    Yield a filesystem Path to the futures products CSV.
+
+    If cfg.REFDATA_FUTURES_PRODUCTS_CSV_PATH is set, yield that path.
+    Otherwise, yield a materialised path to the packaged CSV resource.
+
+    The path may be backed by a temporary file; callers must consume it
+    within the context manager.
+    """
+    override = cfg.REFDATA_FUTURES_PRODUCTS_CSV_PATH
+    if override:
+        yield Path(override)
+        return
+
+    resource = files("mxm.refdata").joinpath("data/futures_products.csv")
+    with as_file(resource) as p:
+        yield Path(p)