tickerforge 0.1.3__py3-none-any.whl

tickerforge/__init__.py

@@ -0,0 +1,12 @@
+from tickerforge.spec_loader import load_spec
+from tickerforge.ticker_generator import TickerForge, generate_ticker_for_contract
+from tickerforge.ticker_parser import ParsedTicker, TickerParser, parse_ticker
+
+__all__ = [
+    "TickerForge",
+    "TickerParser",
+    "ParsedTicker",
+    "generate_ticker_for_contract",
+    "parse_ticker",
+    "load_spec",
+]

tickerforge/calendars.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tickerforge.schedule import ExchangeSchedule
+
+try:
+    import exchange_calendars as xcals
+except ImportError:  # pragma: no cover
+    xcals = None  # type: ignore[assignment,unused-ignore]
+
+EXCHANGE_CALENDAR_ALIASES: dict[str, str] = {
+    "B3": "BVMF",
+    "CME": "CMES",
+    "EUREX": "XEUR",
+    "ICE": "IEPA",
+}
+
+_SCHEDULES: dict[str, ExchangeSchedule] = {}
+
+
+def register_schedules(schedules: dict[str, ExchangeSchedule]) -> None:
+    _SCHEDULES.update(schedules)
+    get_calendar.cache_clear()
+
+
+def _resolve_calendar_name(exchange_code: str) -> str:
+    if xcals is None:
+        raise RuntimeError(
+            "exchange_calendars is not installed and no spec schedule is available "
+            f"for exchange '{exchange_code}'"
+        )
+    code = exchange_code.upper()
+    candidates = [EXCHANGE_CALENDAR_ALIASES.get(code), code]
+
+    for candidate in candidates:
+        if not candidate:
+            continue
+        try:
+            xcals.get_calendar(candidate)
+            return candidate
+        except Exception:
+            continue
+
+    for name in xcals.get_calendar_names():
+        if name.upper() == code:
+            return name
+
+    raise ValueError(f"No calendar found for exchange '{exchange_code}'")
+
+
+@lru_cache(maxsize=16)
+def get_calendar(exchange_code: str):
+    code = exchange_code.upper()
+    if code in _SCHEDULES:
+        from tickerforge.schedule import SpecCalendar
+
+        return SpecCalendar(_SCHEDULES[code])
+
+    calendar_name = _resolve_calendar_name(exchange_code)
+    return xcals.get_calendar(calendar_name)

tickerforge/contract_cycle.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from tickerforge.models import ContractCycle
+from tickerforge.month_codes import code_to_month
+
+BUILTIN_CYCLES: dict[str, list[str]] = {
+    "monthly": ["F", "G", "H", "J", "K", "M", "N", "Q", "U", "V", "X", "Z"],
+    "bimonthly_even": ["G", "J", "M", "Q", "V", "Z"],
+    "quarterly": ["H", "M", "U", "Z"],
+}
+
+
+def resolve_contract_months(
+    contract_cycle: ContractCycle | str, year: int
+) -> list[int]:
+    del year  # The cycle defines valid months; year is kept for a stable API.
+
+    if isinstance(contract_cycle, ContractCycle):
+        month_codes = contract_cycle.months
+    elif isinstance(contract_cycle, str):
+        try:
+            month_codes = BUILTIN_CYCLES[contract_cycle]
+        except KeyError as exc:
+            raise ValueError(f"Unknown contract cycle: {contract_cycle}") from exc
+    else:
+        raise TypeError("contract_cycle must be ContractCycle or str")
+
+    return sorted(code_to_month(code) for code in month_codes)

tickerforge/expiration_rules.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from calendar import monthrange
+from datetime import date
+
+from tickerforge.models import ContractSpec, ExpirationRule
+
+WEEKDAY_NAME_TO_NUMBER = {
+    "monday": 0,
+    "tuesday": 1,
+    "wednesday": 2,
+    "thursday": 3,
+    "friday": 4,
+    "saturday": 5,
+    "sunday": 6,
+}
+
+
+def _month_sessions(calendar, year: int, month: int) -> list[date]:
+    last_day = monthrange(year, month)[1]
+    month_start = date(year, month, 1)
+    month_end = date(year, month, last_day)
+    cal_first = calendar.first_session.date()
+    cal_last = calendar.last_session.date()
+    if month_end < cal_first or month_start > cal_last:
+        return []
+    clip_start = max(month_start, cal_first)
+    clip_end = min(month_end, cal_last)
+    if clip_start > clip_end:
+        return []
+    sessions = calendar.sessions_in_range(
+        clip_start.isoformat(),
+        clip_end.isoformat(),
+    )
+    return [session.date() for session in sessions]
+
+
+def _resolve_first_business_day(calendar, year: int, month: int) -> date:
+    sessions = _month_sessions(calendar, year, month)
+    return sessions[0]
+
+
+def _resolve_last_business_day(calendar, year: int, month: int) -> date:
+    sessions = _month_sessions(calendar, year, month)
+    return sessions[-1]
+
+
+def _resolve_nth_business_day(calendar, year: int, month: int, n: int) -> date:
+    sessions = _month_sessions(calendar, year, month)
+    if n < 1 or n > len(sessions):
+        raise ValueError(f"Invalid nth business day '{n}' for {year}-{month:02d}")
+    return sessions[n - 1]
+
+
+def _resolve_fixed_day(calendar, year: int, month: int, day: int) -> date:
+    last_day = monthrange(year, month)[1]
+    target = date(year, month, min(day, last_day))
+    sessions = _month_sessions(calendar, year, month)
+    for session_day in sessions:
+        if session_day >= target:
+            return session_day
+    return sessions[-1]
+
+
+def _resolve_nearest_weekday_to_day(
+    calendar,
+    year: int,
+    month: int,
+    weekday_name: str,
+    day: int,
+) -> date:
+    weekday_number = WEEKDAY_NAME_TO_NUMBER[weekday_name.lower()]
+    sessions = _month_sessions(calendar, year, month)
+    weekday_sessions = [
+        session_day
+        for session_day in sessions
+        if session_day.weekday() == weekday_number
+    ]
+    if not weekday_sessions:
+        raise ValueError(
+            f"No sessions on weekday '{weekday_name}' for {year}-{month:02d}"
+        )
+
+    last_day = monthrange(year, month)[1]
+    target = date(year, month, min(day, last_day))
+    return min(weekday_sessions, key=lambda value: (abs((value - target).days), value))
+
+
+def _resolve_nth_weekday_of_month(
+    calendar,
+    year: int,
+    month: int,
+    weekday_name: str,
+    n: int,
+) -> date:
+    weekday_number = WEEKDAY_NAME_TO_NUMBER[weekday_name.lower()]
+    sessions = _month_sessions(calendar, year, month)
+    weekday_sessions = [
+        session_day
+        for session_day in sessions
+        if session_day.weekday() == weekday_number
+    ]
+    if n < 1 or n > len(weekday_sessions):
+        raise ValueError(
+            f"Invalid nth weekday '{n}' for weekday '{weekday_name}' "
+            f"in {year}-{month:02d}"
+        )
+    return weekday_sessions[n - 1]
+
+
+def resolve_expiration(
+    contract: ContractSpec,
+    year: int,
+    month: int,
+    expiration_rule: ExpirationRule,
+    calendar,
+) -> date:
+    # Expiration can be rule-based; kept for future product-specific logic.
+    del contract
+
+    rule_type = expiration_rule.type
+    if rule_type == "first_business_day":
+        return _resolve_first_business_day(calendar, year, month)
+    if rule_type == "last_business_day":
+        return _resolve_last_business_day(calendar, year, month)
+    if rule_type == "nth_business_day":
+        if expiration_rule.n is None:
+            raise ValueError("nth_business_day rule requires 'n'")
+        return _resolve_nth_business_day(calendar, year, month, expiration_rule.n)
+    if rule_type == "fixed_day":
+        if expiration_rule.day is None:
+            raise ValueError("fixed_day rule requires 'day'")
+        return _resolve_fixed_day(calendar, year, month, expiration_rule.day)
+    if rule_type == "nearest_weekday_to_day":
+        if expiration_rule.weekday is None or expiration_rule.day is None:
+            raise ValueError("nearest_weekday_to_day rule requires 'weekday' and 'day'")
+        return _resolve_nearest_weekday_to_day(
+            calendar,
+            year,
+            month,
+            expiration_rule.weekday,
+            expiration_rule.day,
+        )
+    if rule_type == "nth_weekday_of_month":
+        if expiration_rule.weekday is None or expiration_rule.n is None:
+            raise ValueError("nth_weekday_of_month rule requires 'weekday' and 'n'")
+        return _resolve_nth_weekday_of_month(
+            calendar,
+            year,
+            month,
+            expiration_rule.weekday,
+            expiration_rule.n,
+        )
+    if rule_type == "schedule":
+        raise NotImplementedError(
+            "schedule expiration rules need external schedule data"
+        )
+
+    raise ValueError(f"Unsupported expiration rule type: {rule_type}")

tickerforge/models.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+if TYPE_CHECKING:
+    from datetime import date, datetime
+
+    from tickerforge.spec_loader import SpecRepository
+
+
+class SessionSegment(BaseModel):
+    """One clock-time trading window; YAML uses the key as ``name`` (not repeated in the value)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    start: str
+    end: str
+
+
+def _sessions_mapping_to_list(sess: dict[str, Any]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for k, v in sess.items():
+        if not isinstance(v, dict):
+            raise ValueError(f"session '{k}' must be an object with start and end")
+        start, end = v.get("start"), v.get("end")
+        if start is None or end is None:
+            raise ValueError(f"session '{k}' requires start and end")
+        out.append({"name": str(k), "start": str(start), "end": str(end)})
+    return out
+
+
+class Asset(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    symbol: str
+    type: str | None = None
+    category: str | None = None
+    description: str | None = None
+    sessions: list[SessionSegment] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _sessions_map_to_segments(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        sess = data.get("sessions")
+        if isinstance(sess, dict):
+            data = {**data, "sessions": _sessions_mapping_to_list(sess)}
+        return data
+
+    @model_validator(mode="after")
+    def _validate_sessions(self) -> Asset:
+        if not self.sessions:
+            raise ValueError("Asset sessions must include at least one segment")
+        if self.sessions[0].name.lower() != "regular":
+            raise ValueError("First session segment must be named 'regular'")
+        return self
+
+    def is_unique_session(self) -> bool:
+        """True if there is exactly one trading band (no implicit pauses between segments)."""
+        return len(self.sessions) == 1
+
+    def default_session(self) -> SessionSegment | None:
+        """The sole session when ``is_unique_session``; otherwise ``None`` (multiple bands)."""
+        return self.sessions[0] if len(self.sessions) == 1 else None
+
+
+class Exchange(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    code: str
+    mic: str | None = None
+    full_name: str | None = None
+    country: str | None = None
+    timezone: str | None = None
+    assets: dict[str, Asset] = Field(default_factory=dict)
+
+
+class ContractCycle(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    name: str
+    description: str | None = None
+    months: list[str] = Field(default_factory=list)
+
+
+class ExpirationRule(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    name: str
+    type: str
+    description: str | None = None
+    weekday: str | None = None
+    day: int | None = None
+    n: int | None = None
+    tags: list[str] = Field(default_factory=list)
+
+
+class ContractSpec(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    symbol: str
+    exchange: str
+    description: str | None = None
+    ticker_format: str = "{symbol}{month_code}{yy}"
+    contract_cycle: str
+    expiration_rule: str
+    contract_multiplier: float | None = None
+    tick_size: float | None = None
+    currency: str | None = None
+    aliases: list[str] = Field(default_factory=list)
+    # Filled at load time from `exchanges/<mic>.yaml` for this symbol (not in contract YAML).
+    sessions: list[SessionSegment] = Field(default_factory=list)
+    exchange_timezone: str | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _sessions_map_to_segments(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        sess = data.get("sessions")
+        if isinstance(sess, dict):
+            data = {**data, "sessions": _sessions_mapping_to_list(sess)}
+        return data
+
+    @model_validator(mode="after")
+    def _validate_sessions(self) -> ContractSpec:
+        if self.sessions and self.sessions[0].name.lower() != "regular":
+            raise ValueError("First session segment must be named 'regular'")
+        return self
+
+    def regular_session(self) -> SessionSegment | None:
+        """The regular band (first segment; clock times in ``exchange_timezone``)."""
+        return self.sessions[0] if self.sessions else None
+
+    def is_unique_session(self) -> bool:
+        """True if there is exactly one trading band (no implicit pauses between segments)."""
+        return len(self.sessions) == 1
+
+    def default_session(self) -> SessionSegment | None:
+        """The sole session when there is only one band; ``None`` if zero or multiple segments."""
+        return self.sessions[0] if len(self.sessions) == 1 else None
+
+    def regular_session_start_end(self) -> tuple[str, str] | None:
+        """Start and end clock times for the regular session, e.g. ``('09:00', '18:30')``."""
+        reg = self.regular_session()
+        if not reg:
+            return None
+        return (reg.start, reg.end)
+
+    def trading_symbol_today(
+        self,
+        spec: SpecRepository | None = None,
+        *,
+        offset: int = 0,
+    ) -> str:
+        """Front-month ticker using bundled spec unless ``spec`` is passed."""
+        from datetime import date
+
+        from tickerforge.spec_loader import load_spec
+        from tickerforge.ticker_generator import generate_ticker_for_contract
+
+        repo = spec if spec is not None else load_spec()
+        return generate_ticker_for_contract(self, date.today(), repo, offset=offset)
+
+    def trading_symbol_for(
+        self,
+        as_of: str | date | datetime,
+        spec: SpecRepository | None = None,
+        *,
+        offset: int = 0,
+    ) -> str:
+        """Front-month ticker for ``as_of``; bundled spec unless ``spec`` is passed."""
+        from tickerforge.spec_loader import load_spec
+        from tickerforge.ticker_generator import generate_ticker_for_contract
+
+        repo = spec if spec is not None else load_spec()
+        return generate_ticker_for_contract(self, as_of, repo, offset=offset)

tickerforge/month_codes.py

@@ -0,0 +1,31 @@
+MONTH_TO_CODE: dict[int, str] = {
+    1: "F",
+    2: "G",
+    3: "H",
+    4: "J",
+    5: "K",
+    6: "M",
+    7: "N",
+    8: "Q",
+    9: "U",
+    10: "V",
+    11: "X",
+    12: "Z",
+}
+
+CODE_TO_MONTH: dict[str, int] = {code: month for month, code in MONTH_TO_CODE.items()}
+
+
+def month_to_code(month: int) -> str:
+    try:
+        return MONTH_TO_CODE[month]
+    except KeyError as exc:
+        raise ValueError(f"Invalid month: {month}") from exc
+
+
+def code_to_month(code: str) -> int:
+    normalized = code.upper()
+    try:
+        return CODE_TO_MONTH[normalized]
+    except KeyError as exc:
+        raise ValueError(f"Invalid month code: {code}") from exc

tickerforge/py.typed

@@ -0,0 +1 @@
+

tickerforge/schedule.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from datetime import date, timedelta
+from pathlib import Path
+
+import yaml
+from dateutil.easter import easter
+
+WEEKDAY_MAP = {
+    "monday": 0,
+    "tuesday": 1,
+    "wednesday": 2,
+    "thursday": 3,
+    "friday": 4,
+}
+
+
+def _nth_weekday_of_month(year: int, month: int, weekday: int, nth: int) -> date:
+    first = date(year, month, 1)
+    diff = (weekday - first.weekday()) % 7
+    first_occ = first + timedelta(days=diff)
+    return first_occ + timedelta(weeks=nth - 1)
+
+
+def _last_weekday_of_month(year: int, month: int, weekday: int) -> date:
+    if month == 12:
+        last_day = date(year + 1, 1, 1) - timedelta(days=1)
+    else:
+        last_day = date(year, month + 1, 1) - timedelta(days=1)
+    diff = (last_day.weekday() - weekday) % 7
+    return last_day - timedelta(days=diff)
+
+
+def _rule_applies(rule: dict, year: int) -> bool:
+    if "from_year" in rule and year < rule["from_year"]:
+        return False
+    if "to_year" in rule and year > rule["to_year"]:
+        return False
+    return True
+
+
+class ExchangeSchedule:
+    def __init__(self, data: dict) -> None:
+        self.exchange: str = data["exchange"]
+        self.timezone: str = data["timezone"]
+        self._holidays = data.get("holidays", {})
+        self._early_closes = data.get("early_closes", {})
+        self._holiday_cache: dict[int, set[date]] = {}
+        self._early_close_cache: dict[int, dict[date, str]] = {}
+
+    def holidays_for_year(self, year: int) -> set[date]:
+        if year in self._holiday_cache:
+            return self._holiday_cache[year]
+
+        holidays: set[date] = set()
+        easter_sunday = easter(year)
+
+        for rule in self._holidays.get("fixed", []):
+            if not _rule_applies(rule, year):
+                continue
+            holidays.add(date(year, rule["month"], rule["day"]))
+
+        for rule in self._holidays.get("easter_offset", []):
+            if not _rule_applies(rule, year):
+                continue
+            holidays.add(easter_sunday + timedelta(days=rule["offset"]))
+
+        for rule in self._holidays.get("nth_weekday", []):
+            if not _rule_applies(rule, year):
+                continue
+            wd = WEEKDAY_MAP[rule["weekday"]]
+            holidays.add(_nth_weekday_of_month(year, rule["month"], wd, rule["nth"]))
+
+        for rule in self._holidays.get("last_weekday", []):
+            if not _rule_applies(rule, year):
+                continue
+            wd = WEEKDAY_MAP[rule["weekday"]]
+            holidays.add(_last_weekday_of_month(year, rule["month"], wd))
+
+        for rule in self._holidays.get("overrides", []):
+            d = date.fromisoformat(rule["date"])
+            if d.year != year:
+                continue
+            if rule["action"] == "add":
+                holidays.add(d)
+            elif rule["action"] == "remove":
+                holidays.discard(d)
+
+        holidays = {d for d in holidays if d.weekday() < 5}
+        self._holiday_cache[year] = holidays
+        return holidays
+
+    def early_closes_for_year(self, year: int) -> dict[date, str]:
+        if year in self._early_close_cache:
+            return self._early_close_cache[year]
+
+        result: dict[date, str] = {}
+        easter_sunday = easter(year)
+
+        for rule in self._early_closes.get("fixed", []):
+            if not _rule_applies(rule, year):
+                continue
+            d = date(year, rule["month"], rule["day"])
+            if d.weekday() < 5:
+                result[d] = rule["open"]
+
+        for rule in self._early_closes.get("easter_offset", []):
+            if not _rule_applies(rule, year):
+                continue
+            d = easter_sunday + timedelta(days=rule["offset"])
+            if d.weekday() < 5:
+                result[d] = rule["open"]
+
+        self._early_close_cache[year] = result
+        return result
+
+    def is_early_close(self, d: date) -> bool:
+        return d in self.early_closes_for_year(d.year)
+
+    def early_close_time(self, d: date) -> str | None:
+        return self.early_closes_for_year(d.year).get(d)
+
+    def is_session(self, d: date) -> bool:
+        if d.weekday() >= 5:
+            return False
+        return d not in self.holidays_for_year(d.year)
+
+    def sessions_in_range(self, start: date, end: date) -> list[date]:
+        result: list[date] = []
+        current = start
+        one_day = timedelta(days=1)
+        while current <= end:
+            if self.is_session(current):
+                result.append(current)
+            current += one_day
+        return result
+
+
+class SpecCalendar:
+    """Wraps ExchangeSchedule to expose the interface expected by expiration_rules.py."""
+
+    def __init__(self, schedule: ExchangeSchedule) -> None:
+        self._schedule = schedule
+        first = date(1990, 1, 1)
+        while not schedule.is_session(first):
+            first += timedelta(days=1)
+        self._first_session = first
+
+        last = date(2035, 12, 31)
+        while not schedule.is_session(last):
+            last -= timedelta(days=1)
+        self._last_session = last
+
+    @property
+    def first_session(self) -> _DateWrapper:
+        return _DateWrapper(self._first_session)
+
+    @property
+    def last_session(self) -> _DateWrapper:
+        return _DateWrapper(self._last_session)
+
+    def sessions_in_range(
+        self, start: str | date, end: str | date
+    ) -> list[_DateWrapper]:
+        s = date.fromisoformat(str(start)) if isinstance(start, str) else start
+        e = date.fromisoformat(str(end)) if isinstance(end, str) else end
+        return [_DateWrapper(d) for d in self._schedule.sessions_in_range(s, e)]
+
+    def is_early_close(self, d: date) -> bool:
+        return self._schedule.is_early_close(d)
+
+    def early_close_time(self, d: date) -> str | None:
+        return self._schedule.early_close_time(d)
+
+
+class _DateWrapper:
+    """Mimics the pandas.Timestamp interface that exchange_calendars returns."""
+
+    def __init__(self, d: date) -> None:
+        self._date = d
+
+    def date(self) -> date:
+        return self._date
+
+    def __repr__(self) -> str:
+        return f"_DateWrapper({self._date})"
+
+
+def load_schedule(path: Path) -> ExchangeSchedule:
+    with path.open("r", encoding="utf-8") as handle:
+        data = yaml.safe_load(handle)
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected YAML mapping in {path}")
+    return ExchangeSchedule(data)
+
+
+def load_schedules(spec_root: Path) -> dict[str, ExchangeSchedule]:
+    schedules_dir = spec_root / "schedules"
+    result: dict[str, ExchangeSchedule] = {}
+    if not schedules_dir.is_dir():
+        return result
+    for yaml_path in sorted(schedules_dir.glob("*.yaml")):
+        schedule = load_schedule(yaml_path)
+        result[schedule.exchange.upper()] = schedule
+    return result