oq-core 0.1.0__py3-none-any.whl

oq_core/__init__.py

@@ -0,0 +1,14 @@
+"""oq-core: shared primitives for the OpenQuant India ecosystem."""
+
+from oq_core.calendar import TradingCalendar
+from oq_core.instrument import Exchange, Instrument, Segment
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Exchange",
+    "Instrument",
+    "Segment",
+    "TradingCalendar",
+    "__version__",
+]

oq_core/calendar.py

@@ -0,0 +1,192 @@
+"""NSE trading calendar.
+
+This module implements a minimal-but-correct NSE equity trading calendar:
+
+* Mon-Fri are trading days.
+* Saturday and Sunday are non-trading days.
+* A curated set of NSE trading holidays is loaded from
+  :data:`HOLIDAYS_BY_YEAR`.
+* Muhurat (Diwali) sessions are special trading days where the date would
+  otherwise be a holiday or where only an evening session is open.
+
+The calendar API is intentionally small and deterministic so that ``oq-data``
+and ``oq-backtest`` can rely on it without pulling pandas at import time.
+
+Holiday lists are maintained by year. They are best-effort and should be
+verified against the NSE annual circular for any production usage.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import date, datetime, time, timedelta
+
+NSE_OPEN = time(9, 15)
+NSE_CLOSE = time(15, 30)
+
+
+@dataclass(frozen=True, slots=True)
+class MuhuratSession:
+    """A Diwali muhurat trading session (evening, typically ~1 hour)."""
+
+    session_date: date
+    open_time: time
+    close_time: time
+
+
+# NSE trading holidays. Source: NSE annual holiday circulars.
+# Only includes fully-closed equity trading days (not settlement holidays).
+# This list is best-effort; consumers should verify against the NSE circular.
+HOLIDAYS_BY_YEAR: dict[int, frozenset[date]] = {
+    2023: frozenset(
+        {
+            date(2023, 1, 26),  # Republic Day
+            date(2023, 3, 7),  # Holi
+            date(2023, 3, 30),  # Ram Navami
+            date(2023, 4, 4),  # Mahavir Jayanti
+            date(2023, 4, 7),  # Good Friday
+            date(2023, 4, 14),  # Dr. Ambedkar Jayanti
+            date(2023, 5, 1),  # Maharashtra Day
+            date(2023, 6, 28),  # Bakri Id
+            date(2023, 8, 15),  # Independence Day
+            date(2023, 9, 19),  # Ganesh Chaturthi
+            date(2023, 10, 2),  # Gandhi Jayanti
+            date(2023, 10, 24),  # Dussehra
+            date(2023, 11, 14),  # Diwali Balipratipada
+            date(2023, 11, 27),  # Guru Nanak Jayanti
+            date(2023, 12, 25),  # Christmas
+        }
+    ),
+    2024: frozenset(
+        {
+            date(2024, 1, 26),  # Republic Day
+            date(2024, 3, 8),  # Mahashivratri
+            date(2024, 3, 25),  # Holi
+            date(2024, 3, 29),  # Good Friday
+            date(2024, 4, 11),  # Id-Ul-Fitr
+            date(2024, 4, 17),  # Ram Navami
+            date(2024, 5, 1),  # Maharashtra Day
+            date(2024, 5, 20),  # General Elections (Mumbai)
+            date(2024, 6, 17),  # Bakri Id
+            date(2024, 7, 17),  # Muharram
+            date(2024, 8, 15),  # Independence Day
+            date(2024, 10, 2),  # Gandhi Jayanti
+            date(2024, 11, 1),  # Diwali Laxmi Pujan (full holiday; muhurat session in evening)
+            date(2024, 11, 15),  # Guru Nanak Jayanti
+            date(2024, 12, 25),  # Christmas
+        }
+    ),
+    2025: frozenset(
+        {
+            date(2025, 2, 26),  # Mahashivratri
+            date(2025, 3, 14),  # Holi
+            date(2025, 3, 31),  # Id-Ul-Fitr
+            date(2025, 4, 10),  # Mahavir Jayanti
+            date(2025, 4, 14),  # Dr. Ambedkar Jayanti
+            date(2025, 4, 18),  # Good Friday
+            date(2025, 5, 1),  # Maharashtra Day
+            date(2025, 8, 15),  # Independence Day
+            date(2025, 8, 27),  # Ganesh Chaturthi
+            date(2025, 10, 2),  # Gandhi Jayanti / Dussehra
+            date(2025, 10, 21),  # Diwali Laxmi Pujan (muhurat session in evening)
+            date(2025, 10, 22),  # Diwali Balipratipada
+            date(2025, 11, 5),  # Guru Nanak Jayanti
+            date(2025, 12, 25),  # Christmas
+        }
+    ),
+}
+
+
+# Muhurat (Diwali) trading sessions. These are evening sessions on what would
+# otherwise be a non-trading day.
+MUHURAT_SESSIONS: tuple[MuhuratSession, ...] = (
+    MuhuratSession(date(2023, 11, 12), time(18, 15), time(19, 15)),
+    MuhuratSession(date(2024, 11, 1), time(18, 0), time(19, 0)),
+    MuhuratSession(date(2025, 10, 21), time(13, 45), time(14, 45)),
+)
+
+
+class TradingCalendar:
+    """NSE equity trading calendar.
+
+    Parameters
+    ----------
+    holidays:
+        Optional override mapping of year to holiday set. Defaults to the
+        bundled :data:`HOLIDAYS_BY_YEAR`.
+    muhurat:
+        Optional override of muhurat sessions. Defaults to
+        :data:`MUHURAT_SESSIONS`.
+    """
+
+    def __init__(
+        self,
+        holidays: dict[int, frozenset[date]] | None = None,
+        muhurat: tuple[MuhuratSession, ...] | None = None,
+    ) -> None:
+        self._holidays: dict[int, frozenset[date]] = (
+            dict(holidays) if holidays is not None else dict(HOLIDAYS_BY_YEAR)
+        )
+        self._muhurat: dict[date, MuhuratSession] = {
+            session.session_date: session
+            for session in (muhurat if muhurat is not None else MUHURAT_SESSIONS)
+        }
+
+    def is_weekend(self, day: date) -> bool:
+        return day.weekday() >= 5
+
+    def is_holiday(self, day: date) -> bool:
+        """True if ``day`` is on the published NSE holiday list."""
+        return day in self._holidays.get(day.year, frozenset())
+
+    def muhurat_session(self, day: date) -> MuhuratSession | None:
+        """Return the muhurat session for ``day``, if any."""
+        return self._muhurat.get(day)
+
+    def is_session(self, day: date) -> bool:
+        """True if regular trading happens on ``day`` (excludes muhurat-only days)."""
+        if self.is_weekend(day):
+            return False
+        return not self.is_holiday(day)
+
+    def is_trading_day(self, day: date) -> bool:
+        """True if any trading occurs on ``day`` (regular session OR muhurat)."""
+        if self.is_session(day):
+            return True
+        return day in self._muhurat
+
+    def next_session(self, day: date) -> date:
+        """Smallest ``d > day`` that is a regular session."""
+        candidate = day + timedelta(days=1)
+        while not self.is_session(candidate):
+            candidate += timedelta(days=1)
+        return candidate
+
+    def previous_session(self, day: date) -> date:
+        """Largest ``d < day`` that is a regular session."""
+        candidate = day - timedelta(days=1)
+        while not self.is_session(candidate):
+            candidate -= timedelta(days=1)
+        return candidate
+
+    def sessions(self, start: date, end: date) -> Iterator[date]:
+        """Yield regular trading sessions in ``[start, end]`` inclusive."""
+        if end < start:
+            return
+        current = start
+        while current <= end:
+            if self.is_session(current):
+                yield current
+            current += timedelta(days=1)
+
+    def session_count(self, start: date, end: date) -> int:
+        """Number of regular trading sessions in ``[start, end]`` inclusive."""
+        return sum(1 for _ in self.sessions(start, end))
+
+    def is_market_open(self, when: datetime) -> bool:
+        """True if the regular cash market is open at ``when`` (naive local IST)."""
+        day = when.date()
+        if not self.is_session(day):
+            return False
+        return NSE_OPEN <= when.time() <= NSE_CLOSE

oq_core/instrument.py

@@ -0,0 +1,92 @@
+"""Instrument model: a typed representation of an exchange-listed instrument."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+
+_ISIN_PATTERN = re.compile(r"^[A-Z]{2}[A-Z0-9]{9}\d$")
+_SYMBOL_PATTERN = re.compile(r"^[A-Z0-9][A-Z0-9&\-\.]{0,49}$")
+
+
+class Exchange(StrEnum):
+    """Indian exchanges supported by OpenQuant."""
+
+    NSE = "NSE"
+    BSE = "BSE"
+
+
+class Segment(StrEnum):
+    """Market segments within an exchange."""
+
+    EQ = "EQ"
+    FUT = "FUT"
+    OPT = "OPT"
+    CDS = "CDS"
+    COM = "COM"
+
+
+@dataclass(frozen=True, slots=True)
+class Instrument:
+    """A single exchange-listed instrument.
+
+    Identity is ``(exchange, segment, symbol)``. ``isin`` is the canonical
+    cross-exchange identifier used to follow corporate actions and renames
+    (e.g. the HDFC/HDFC Bank merger).
+
+    Parameters
+    ----------
+    symbol:
+        Trading symbol as listed on the exchange (uppercase). For NSE EQ this
+        is the tradingsymbol (e.g. ``"RELIANCE"``).
+    isin:
+        12-character ISIN (e.g. ``"INE002A01018"``). Required for equities;
+        optional for derivatives.
+    exchange:
+        Listing exchange.
+    segment:
+        Market segment (EQ, FUT, OPT, CDS, COM).
+    lot_size:
+        Minimum tradable quantity. ``1`` for cash equities, varies for F&O.
+    tick_size:
+        Minimum price increment in INR. Defaults to ``0.05``.
+    name:
+        Human-readable company / contract name.
+    """
+
+    symbol: str
+    exchange: Exchange = Exchange.NSE
+    segment: Segment = Segment.EQ
+    isin: str | None = None
+    lot_size: int = 1
+    tick_size: float = 0.05
+    name: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.symbol, str) or not self.symbol:
+            raise ValueError("symbol must be a non-empty string")
+        if not _SYMBOL_PATTERN.match(self.symbol):
+            raise ValueError(
+                f"invalid symbol {self.symbol!r}: must be uppercase alphanumeric "
+                "(plus & - .), up to 50 chars"
+            )
+        if self.isin is not None and not _ISIN_PATTERN.match(self.isin):
+            raise ValueError(
+                f"invalid ISIN {self.isin!r}: expected 12 chars matching "
+                "country(2) + alphanumeric(9) + checksum(1)"
+            )
+        if self.segment is Segment.EQ and self.isin is None:
+            raise ValueError("equity instruments require an ISIN")
+        if self.lot_size < 1:
+            raise ValueError(f"lot_size must be >= 1, got {self.lot_size}")
+        if self.tick_size <= 0:
+            raise ValueError(f"tick_size must be > 0, got {self.tick_size}")
+
+    @property
+    def key(self) -> tuple[str, str, str]:
+        """Stable identity tuple suitable for dict keys."""
+        return (self.exchange.value, self.segment.value, self.symbol)
+
+    def __str__(self) -> str:
+        return f"{self.exchange.value}:{self.segment.value}:{self.symbol}"

oq_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: oq-core
+Version: 0.1.0
+Summary: Shared primitives for the OpenQuant India ecosystem: Instrument, TradingCalendar, config.
+Project-URL: Homepage, https://github.com/revorhq/openquant
+Project-URL: Repository, https://github.com/revorhq/openquant
+Project-URL: Issues, https://github.com/revorhq/openquant/issues
+Author: OpenQuant India Contributors
+License: Apache-2.0
+Keywords: backtesting,finance,india,nse,quant,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# oq-core
+
+Shared primitives for the OpenQuant India ecosystem.
+
+- `Instrument` — typed model for an exchange-listed instrument (symbol, ISIN, exchange, segment, lot size).
+- `TradingCalendar` — NSE trading calendar with holidays, weekends, and muhurat sessions.
+
+Install:
+
+```bash
+pip install oq-core
+```
+
+See the [main repository](https://github.com/openquant-india/openquant) for the full project, license, and disclaimers.

oq_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+oq_core/__init__.py,sha256=p2Q_VxgUTijbNtvJUsMbrlbzqJrUzO270K48YGfyPlY,304
+oq_core/calendar.py,sha256=56xPuwsMsUKGcho2ywZGtV4zNZiK7X46gjzlUSmTTGY,7180
+oq_core/instrument.py,sha256=gLez-KM5bsUj51rypSI64TEsN1mYMGhYH__AkW_PEMQ,2963
+oq_core-0.1.0.dist-info/METADATA,sha256=5OtMJmE9h9yVmGshctWmVh6f5FPbGOYcdg-6X3HiqtY,1422
+oq_core-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+oq_core-0.1.0.dist-info/RECORD,,

oq_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any