fix(python): complete type stubs for string enums and the util submodule (#887)

The type-stub surface left several runtime exports resolving only through the module-level `__getattr__` fallback to `Any`, so mypy users typing against `Interval.M_1`, `Right.CALL`, or the `thetadatadx.util` lookups got no checking at all.

Add explicit class declarations for the six string-valued parameter enums (`Right`, `Venue`, `Interval`, `RateType`, `RequestType`, `Version`) with their exact members, the `value` accessor, and the `__str__` / `__repr__` / `__eq__` / `__hash__` surface. Ship a `util.pyi` for the `thetadatadx.util` submodule declaring all fourteen public lookup and conversion functions with their real signatures and return types. Add the missing `__bool__` and `__repr__` to `FlatFileRowList`.

Verified with `mypy.stubtest` against the built extension under the repo's CI flags: the newly declared symbols match the runtime exactly, with no new discrepancies. The cross-binding parity gate stays clean.

Co-authored-by: preview <noreply@anthropic.com>

Author: userFRM

sdks/python/python/thetadatadx/__init__.pyi

@@ -394,6 +394,255 @@ class SecType:
         ...
 
 
+# ─────────────────────────────────────────────────────────────────────
+# String-valued parameter enums
+# ─────────────────────────────────────────────────────────────────────
+#
+# Each class is a frozen, value-comparable handle whose members are the
+# only valid instances. The backing ``value`` is the lowercase wire token
+# the endpoints expect; ``str(member)`` returns that token and ``repr``
+# returns ``"<Class>.<token>"``. Instances are hashable and compare by
+# value, so they are usable as dict keys and in sets.
+
+
+@final
+class Right:
+    """Option right accepted by the contract and request builders."""
+
+    CALL: Right
+    """Call options."""
+    PUT: Right
+    """Put options."""
+    BOTH: Right
+    """Both calls and puts."""
+
+    @property
+    def value(self) -> str:
+        """The wire token for this right (e.g. ``"call"``)."""
+        ...
+
+    def __str__(self) -> str:
+        """Return the wire token (e.g. ``"call"``)."""
+        ...
+
+    def __repr__(self) -> str:
+        """Return a representation (e.g. ``"Right.call"``)."""
+        ...
+
+    def __eq__(self, other: object) -> bool:
+        """Return whether ``other`` is the same right."""
+        ...
+
+    def __hash__(self) -> int:
+        """Return a hash consistent with :meth:`__eq__`."""
+        ...
+
+
+@final
+class Venue:
+    """Quote-venue selector for venue-scoped quote requests."""
+
+    NQB: Venue
+    """The national best bid and offer composite venue."""
+    UTP_CTA: Venue
+    """The combined UTP / CTA tape venue."""
+
+    @property
+    def value(self) -> str:
+        """The wire token for this venue (e.g. ``"nqb"``)."""
+        ...
+
+    def __str__(self) -> str:
+        """Return the wire token (e.g. ``"nqb"``)."""
+        ...
+
+    def __repr__(self) -> str:
+        """Return a representation (e.g. ``"Venue.nqb"``)."""
+        ...
+
+    def __eq__(self, other: object) -> bool:
+        """Return whether ``other`` is the same venue."""
+        ...
+
+    def __hash__(self) -> int:
+        """Return a hash consistent with :meth:`__eq__`."""
+        ...
+
+
+@final
+class Interval:
+    """Aggregation interval for bar / OHLC historical requests."""
+
+    TICK: Interval
+    """Per-tick, no aggregation."""
+    MS_10: Interval
+    """10-millisecond bars."""
+    MS_100: Interval
+    """100-millisecond bars."""
+    MS_500: Interval
+    """500-millisecond bars."""
+    S_1: Interval
+    """1-second bars."""
+    S_5: Interval
+    """5-second bars."""
+    S_10: Interval
+    """10-second bars."""
+    S_15: Interval
+    """15-second bars."""
+    S_30: Interval
+    """30-second bars."""
+    M_1: Interval
+    """1-minute bars."""
+    M_5: Interval
+    """5-minute bars."""
+    M_10: Interval
+    """10-minute bars."""
+    M_15: Interval
+    """15-minute bars."""
+    M_30: Interval
+    """30-minute bars."""
+    H_1: Interval
+    """1-hour bars."""
+
+    @property
+    def value(self) -> str:
+        """The wire token for this interval (e.g. ``"1m"``)."""
+        ...
+
+    def __str__(self) -> str:
+        """Return the wire token (e.g. ``"1m"``)."""
+        ...
+
+    def __repr__(self) -> str:
+        """Return a representation (e.g. ``"Interval.1m"``)."""
+        ...
+
+    def __eq__(self, other: object) -> bool:
+        """Return whether ``other`` is the same interval."""
+        ...
+
+    def __hash__(self) -> int:
+        """Return a hash consistent with :meth:`__eq__`."""
+        ...
+
+
+@final
+class RateType:
+    """Reference-rate selector for interest-rate requests."""
+
+    SOFR: RateType
+    """The Secured Overnight Financing Rate."""
+    TREASURY_M1: RateType
+    """1-month Treasury rate."""
+    TREASURY_M3: RateType
+    """3-month Treasury rate."""
+    TREASURY_M6: RateType
+    """6-month Treasury rate."""
+    TREASURY_Y1: RateType
+    """1-year Treasury rate."""
+    TREASURY_Y2: RateType
+    """2-year Treasury rate."""
+    TREASURY_Y3: RateType
+    """3-year Treasury rate."""
+    TREASURY_Y5: RateType
+    """5-year Treasury rate."""
+    TREASURY_Y7: RateType
+    """7-year Treasury rate."""
+    TREASURY_Y10: RateType
+    """10-year Treasury rate."""
+    TREASURY_Y20: RateType
+    """20-year Treasury rate."""
+    TREASURY_Y30: RateType
+    """30-year Treasury rate."""
+
+    @property
+    def value(self) -> str:
+        """The wire token for this rate (e.g. ``"sofr"``)."""
+        ...
+
+    def __str__(self) -> str:
+        """Return the wire token (e.g. ``"sofr"``)."""
+        ...
+
+    def __repr__(self) -> str:
+        """Return a representation (e.g. ``"RateType.sofr"``)."""
+        ...
+
+    def __eq__(self, other: object) -> bool:
+        """Return whether ``other`` is the same rate type."""
+        ...
+
+    def __hash__(self) -> int:
+        """Return a hash consistent with :meth:`__eq__`."""
+        ...
+
+
+@final
+class RequestType:
+    """Per-row request kind for the flat-file and bar request builders."""
+
+    TRADE: RequestType
+    """Trade rows."""
+    QUOTE: RequestType
+    """Quote rows."""
+    EOD: RequestType
+    """End-of-day summary rows."""
+    OHLC: RequestType
+    """Open / high / low / close bar rows."""
+
+    @property
+    def value(self) -> str:
+        """The wire token for this request type (e.g. ``"trade"``)."""
+        ...
+
+    def __str__(self) -> str:
+        """Return the wire token (e.g. ``"trade"``)."""
+        ...
+
+    def __repr__(self) -> str:
+        """Return a representation (e.g. ``"RequestType.trade"``)."""
+        ...
+
+    def __eq__(self, other: object) -> bool:
+        """Return whether ``other`` is the same request type."""
+        ...
+
+    def __hash__(self) -> int:
+        """Return a hash consistent with :meth:`__eq__`."""
+        ...
+
+
+@final
+class Version:
+    """Endpoint schema-version selector."""
+
+    LATEST: Version
+    """The latest schema version the server serves."""
+    V1: Version
+    """The pinned first schema version."""
+
+    @property
+    def value(self) -> str:
+        """The wire token for this version (e.g. ``"latest"``)."""
+        ...
+
+    def __str__(self) -> str:
+        """Return the wire token (e.g. ``"latest"``)."""
+        ...
+
+    def __repr__(self) -> str:
+        """Return a representation (e.g. ``"Version.latest"``)."""
+        ...
+
+    def __eq__(self, other: object) -> bool:
+        """Return whether ``other`` is the same version."""
+        ...
+
+    def __hash__(self) -> int:
+        """Return a hash consistent with :meth:`__eq__`."""
+        ...
+
+
 @final
 class Subscription:
     """Typed market-data subscription (per-contract or full-stream)."""
@@ -1740,6 +1989,14 @@ class FlatFileRowList:
         """Return the number of rows."""
         ...
 
+    def __bool__(self) -> bool:
+        """Return whether the list holds at least one row."""
+        ...
+
+    def __repr__(self) -> str:
+        """Return a representation (e.g. ``"FlatFileRowList(128 rows)"``)."""
+        ...
+
     def to_list(self) -> List[Any]:
         """Return the rows as a list of dicts, one dict per row."""
         ...

sdks/python/python/thetadatadx/util.pyi

@@ -0,0 +1,115 @@
+"""Cross-language lookup and conversion helpers.
+
+The ``thetadatadx.util`` submodule exposes the same finite lookup tables
+and tick-field conversions the other language bindings share: trade and
+quote condition vocabulary, exchange name / symbol lookups, the
+calendar-day status vocabulary, the ``(date, ms-of-day)`` to epoch-
+milliseconds conversion, and the signed / unsigned trade-sequence
+re-encoding.
+
+All functions are pure and side-effect free.
+
+Example:
+    >>> import thetadatadx.util as util
+    >>> util.condition_name(0)
+    'REGULAR'
+    >>> util.exchange_symbol(3)
+    'NYSE'
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def condition_name(code: int) -> str:
+    """Return the trade-condition name for ``code`` (e.g. ``"REGULAR"``).
+
+    Returns a placeholder name for codes outside the known table.
+    """
+    ...
+
+
+def condition_description(code: int) -> str:
+    """Return the human-readable trade-condition description for ``code``."""
+    ...
+
+
+def is_cancel(code: int) -> bool:
+    """Return whether the trade-condition ``code`` marks a cancellation."""
+    ...
+
+
+def updates_volume(code: int) -> bool:
+    """Return whether a trade with condition ``code`` updates daily volume."""
+    ...
+
+
+def quote_condition_name(code: int) -> str:
+    """Return the quote-condition name for ``code``."""
+    ...
+
+
+def quote_condition_description(code: int) -> str:
+    """Return the human-readable quote-condition description for ``code``."""
+    ...
+
+
+def is_firm(code: int) -> bool:
+    """Return whether the quote-condition ``code`` is a firm quote."""
+    ...
+
+
+def is_halted(code: int) -> bool:
+    """Return whether the quote-condition ``code`` marks a trading halt."""
+    ...
+
+
+def exchange_name(code: int) -> str:
+    """Return the exchange name for ``code`` (e.g. ``"NewYorkStockExchange"``)."""
+    ...
+
+
+def exchange_symbol(code: int) -> str:
+    """Return the short exchange symbol for ``code`` (e.g. ``"NYSE"``)."""
+    ...
+
+
+def calendar_status_name(code: int) -> str:
+    """Return the calendar-day status text for ``code``.
+
+    Maps ``0`` to ``"open"``, ``1`` to ``"early_close"``, ``2`` to
+    ``"full_close"``, and ``3`` to ``"weekend"``; returns ``"UNKNOWN"``
+    for codes outside the table.
+    """
+    ...
+
+
+def timestamp_ms(date: int, ms_of_day: int) -> Optional[int]:
+    """Combine an Eastern-Time ``YYYYMMDD`` ``date`` and ``ms_of_day``.
+
+    Returns Unix epoch milliseconds (UTC, DST-aware), or ``None`` when
+    ``date`` is ``0`` or either input is out of domain. Usable with any
+    ``(date, *_ms_of_day)`` pair on the tick structs.
+    """
+    ...
+
+
+def sequence_signed_to_unsigned(signed_value: int) -> int:
+    """Convert a signed wire-encoded trade sequence to its unsigned form.
+
+    ``signed_value`` must lie in the i32 wire range
+    (``-2_147_483_648 ..= 2_147_483_647``); a value outside that domain
+    is rejected with :class:`ValueError`.
+    """
+    ...
+
+
+def sequence_unsigned_to_signed(unsigned_value: int) -> int:
+    """Convert an unsigned monotonic trade sequence back to signed wire form.
+
+    ``unsigned_value`` must lie in the unsigned wire range
+    (``0 ..= 2**32 - 1``); a value above that domain is rejected with
+    :class:`ValueError`.
+    """
+    ...