feat: ship py.typed so the package is checked as typed

Without the PEP 561 marker, mypy skips the installed package and reports
import-untyped, and strict users must set ignore_missing_imports, which
turns every massive type into Any.

- Add massive/py.typed. The existing packages entry in pyproject.toml
  already includes it in the wheel and sdist.
- Re-export RESTClient and WebSocketClient explicitly ("X as X"), so
  "from massive import RESTClient" passes --strict, which does not treat
  plain imports in a typed package as re-exports. This adds no __all__,
  so "from massive import *" exports exactly the names it did before.
- Add test_rest/test_exports.py, which fails if any package stops
  exporting, through "from <package> import *", a name it exported
  before this change.
- Add test_rest/typing_consumer.py, a small strict user of the public
  API that is type-checked but never run. It iterates list_* results,
  indexes get_* lists, checks that raw=True gives HTTPResponse, builds
  models with keyword arguments, pins each corrected hint with
  assert_type, and keeps a sample of code written for earlier releases
  (isinstance narrowing, an int CUSIP) to show it still type-checks.
- make static checks it with mypy --strict from inside test_rest/, so
  massive resolves to the installed package as it does for users. It
  fails if py.typed goes missing or any of the above regresses.

Author: chipkent

Makefile

@@ -27,6 +27,9 @@ style:
 ## Check static types
 static:
 	poetry run mypy massive test_* examples
+	@# From test_rest/, massive resolves to the installed package, as it does
+	@# for users, so this also fails if the package stops shipping py.typed.
+	cd test_rest && poetry run mypy --strict typing_consumer.py
 
 ## Check code style and static types
 lint: style static

massive/__init__.py

@@ -1,6 +1,6 @@
-from .rest import RESTClient
+from .rest import RESTClient as RESTClient
 from .rest.base import version
-from .websocket import WebSocketClient
+from .websocket import WebSocketClient as WebSocketClient
 from .exceptions import *
 
 __version__ = version

massive/py.typed

@@ -0,0 +1,106 @@
+"""Guard the names that ``from <package> import *`` exports.
+
+Code that does ``from massive.rest.models import *`` (or the same for any
+other package below) depends on every name it got before. This test fails if
+a package stops exporting a name it exported before type-checking support was
+added (commit e462088, just after v2.9.0). Adding names is fine.
+
+The snapshots are the complete star-export of each package at that commit,
+including incidental names such as ``Optional`` or ``logging``: removing one
+of those could still break a caller that relied on it. To remove a name on
+purpose, delete it from the snapshot in the same change.
+"""
+
+import importlib
+import unittest
+
+# Names that ``from <package> import *`` exported at commit e462088.
+BASELINE_EXPORTS = {
+    "massive": """
+        AuthError BadResponse RESTClient WebSocketClient certs exceptions logging
+        modelclass rest version websocket
+    """.split(),
+    "massive.rest": """
+        AggsClient Any BASE BenzingaClient ConditionsClient ContractsClient Dict
+        DividendsClient ENV_KEY EconomyClient EtfGlobalClient ExchangesClient
+        FinancialsClient FuturesClient IndicatorsClient MarketsClient Optional
+        QuotesClient RESTClient SnapshotClient SplitsClient SummariesClient
+        TickersClient TmxClient TradesClient VXClient aggs base benzinga
+        ca_bundle_path economy etf_global financials futures indicators logger
+        models os quotes reference snapshot summaries tmx trades vX
+    """.split(),
+    "massive.rest.models": """
+        Agg Any AssetClass BalanceSheet Branding CashFlowStatement CompanyAddress
+        ComprehensiveIncome Condition Consolidated CryptoTrade DailyOpenCloseAgg
+        DataPoint DataType DayOptionContractSnapshot Dict Direction Disclosure
+        DisclosureTaxonomy Dividend DividendType EMAIndicatorResults Enum Exchange
+        ExchangeType Filing13F Filing8K FilingFootnote FilingForm3 FilingForm4
+        FilingIndex FilingSection FinancialBalanceSheet FinancialCashFlowStatement
+        FinancialFloat FinancialIncomeStatement FinancialRatio Financials ForexQuote
+        Frequency FuturesAgg FuturesContract FuturesExchange FuturesMarketStatus
+        FuturesProduct FuturesQuote FuturesSchedule FuturesSnapshot
+        FuturesSnapshotDetails FuturesSnapshotMinute FuturesSnapshotQuote
+        FuturesSnapshotSession FuturesSnapshotTrade FuturesTrade Greeks
+        GroupedDailyAgg IPOListing IncomeStatement IndicatorUnderlying
+        IndicatorValue IndicesSession IndicesSnapshot Insight LastForexQuote
+        LastQuote LastQuoteOptionContractSnapshot LastTrade
+        LastTradeOptionContractSnapshot LaunchPadOptions List Locale
+        MACDIndicatorResults MACDIndicatorValue Market MarketCenter MarketCurrencies
+        MarketExchanges MarketHoliday MarketIndices MarketStatus MinuteSnapshot
+        OptionContractSnapshot OptionDetails Optional Options OptionsContract Order
+        OrderBookQuote Precision PreviousCloseAgg Publisher Quote
+        RSIIndicatorResults RealTimeCurrencyConversion RelatedCompany RiskFactor
+        RiskFactorTaxonomy SIP SMAIndicatorResults SeriesType Session ShortInterest
+        ShortVolume SingleIndicatorResults SipMapping SnapshotMarketType
+        SnapshotTickerFullBook Sort Split StockDividend StockFinancial StockSplit
+        SummaryResult Ticker TickerChange TickerChangeEvent TickerChangeResults
+        TickerDetails TickerNews TickerSnapshot TickerTypes Timeframe Trade
+        Underlying UnderlyingAsset Union UniversalSnapshot UniversalSnapshotDetails
+        UniversalSnapshotLastMinute UniversalSnapshotLastQuote
+        UniversalSnapshotLastTrade UniversalSnapshotSession
+        UniversalSnapshotUnderlyingAsset UpdateRules aggs benzinga common conditions
+        contracts dataclass dividends economy etf_global exchanges financials
+        futures indicators markets modelclass quotes request snapshot splits
+        summaries tickers tmx trades
+    """.split(),
+    "massive.websocket": """
+        Any AuthError Awaitable Callable ClientConnection ConnectionClosedError
+        ConnectionClosedOK Counter CryptoQuote CryptoTrade CurrencyAgg Dict Enum
+        EquityAgg EquityQuote EquityTrade EventType FairMarketValue Feed ForexQuote
+        FromDictProtocol FuturesAgg FuturesQuote FuturesTrade Imbalance IndexValue
+        LaunchpadValue Level2Book LimitUpLimitDown List MARKET_EVENT_MAP Market
+        NewType OK_STATUSES Optional Protocol Set Type Union WebSocketClient
+        WebSocketMessage asyncio ca_bundle_path cast common connect env_key
+        get_logger json logger logging modelclass models os parse parse_single ssl
+        time
+    """.split(),
+    "massive.websocket.models": """
+        Any CryptoQuote CryptoTrade CurrencyAgg Dict Enum EquityAgg EquityQuote
+        EquityTrade EventType FairMarketValue Feed ForexQuote FromDictProtocol
+        FuturesAgg FuturesQuote FuturesTrade Imbalance IndexValue LaunchpadValue
+        Level2Book LimitUpLimitDown List MARKET_EVENT_MAP Market NewType Optional
+        Protocol Type Union WebSocketMessage cast common logging modelclass models
+        parse parse_single
+    """.split(),
+}
+
+
+def star_exports(module_name):
+    """Return the names ``from module_name import *`` binds."""
+    module = importlib.import_module(module_name)
+    names = getattr(module, "__all__", None)
+    if names is None:
+        names = [n for n in vars(module) if not n.startswith("_")]
+    return set(names)
+
+
+class StarExportsTest(unittest.TestCase):
+    def test_no_name_removed(self):
+        for package, names in BASELINE_EXPORTS.items():
+            with self.subTest(package=package):
+                missing = sorted(set(names) - star_exports(package))
+                self.assertEqual(missing, [], f"no longer exported by {package}")
+
+
+if __name__ == "__main__":
+    unittest.main()

test_rest/test_exports.py

@@ -0,0 +1,150 @@
+"""Typical user code, checked with ``mypy --strict`` but never run.
+
+``make static`` checks this file from inside ``test_rest/``, so ``massive``
+resolves to the installed package rather than the source tree, exactly as it
+does for a user. That check fails if:
+
+- the package stops shipping ``py.typed`` (mypy reports ``import-untyped``);
+- a public name stops being re-exported from ``massive``;
+- a REST method's default call no longer returns the model type, so
+  iterating, indexing or reading attributes needs an ``isinstance`` check;
+- ``raw=True`` no longer returns ``HTTPResponse``;
+- a model constructor stops accepting its fields as keywords;
+- a corrected hint regresses. ``assert_type`` checks the exact type, so
+  ``Optional[int]`` does not pass where ``Optional[float]`` is expected;
+- code written for earlier releases, which narrows each result with
+  ``isinstance`` and passes an ``int`` CUSIP, stops type-checking.
+
+The file is named so that unittest discovery does not import it.
+"""
+
+from typing import Iterator, List, Optional, Union
+
+from typing_extensions import assert_type
+from urllib3 import HTTPResponse
+
+from massive import AuthError, BadResponse, RESTClient, WebSocketClient
+from massive.rest.models import (
+    Agg,
+    IPOListing,
+    LastTrade,
+    PreviousCloseAgg,
+    ShortInterest,
+    ShortVolume,
+    Ticker,
+)
+from massive.rest.models.economy import TreasuryYield
+from massive.websocket.models import CryptoQuote, IndexValue, WebSocketMessage
+
+
+def ticker_symbols(client: RESTClient) -> List[str]:
+    # list_* yields models; no isinstance check is needed to read them.
+    return [t.ticker for t in client.list_tickers(market="stocks") if t.ticker]
+
+
+def apple_tickers(client: RESTClient) -> List[Ticker]:
+    # A CUSIP is a string; an int is still accepted for backward compatibility.
+    return list(client.list_tickers(cusip="037833100")) + list(
+        client.list_tickers(cusip=37833100)
+    )
+
+
+def first_close(client: RESTClient) -> Optional[float]:
+    # get_* list endpoints can be indexed directly.
+    bars = client.get_aggs("AAPL", 1, "day", "2024-01-02", "2024-01-31")
+    assert_type(bars, List[Agg])
+    return bars[0].close if bars else None
+
+
+def previous_close(client: RESTClient) -> Optional[float]:
+    aggs = client.get_previous_close_agg("AAPL")
+    assert_type(aggs, List[PreviousCloseAgg])
+    return aggs[0].close if aggs else None
+
+
+def last_price(client: RESTClient) -> Optional[float]:
+    trade = client.get_last_trade("AAPL")
+    assert_type(trade, LastTrade)
+    return trade.price
+
+
+def paginated(client: RESTClient) -> None:
+    assert_type(
+        client.list_aggs("AAPL", 1, "day", "2024-01-02", "2024-01-31"), Iterator[Agg]
+    )
+    assert_type(client.list_treasury_yields(), Iterator[TreasuryYield])
+    assert_type(client.list_short_interest(ticker="AAPL"), Iterator[ShortInterest])
+    assert_type(client.list_short_volume(ticker="AAPL"), Iterator[ShortVolume])
+    assert_type(client.vx.list_ipos(), Iterator[IPOListing])
+
+
+def raw_status(client: RESTClient) -> int:
+    resp = client.get_aggs("AAPL", 1, "day", "2024-01-02", "2024-01-31", raw=True)
+    assert_type(resp, HTTPResponse)
+    assert_type(client.list_tickers(raw=True), HTTPResponse)
+    assert_type(client.get_last_trade("AAPL", raw=True), HTTPResponse)
+    return resp.status
+
+
+def raw_flag(client: RESTClient, raw: bool) -> None:
+    # A non-literal flag gets the full union, as before.
+    assert_type(client.get_last_trade("AAPL", raw=raw), Union[LastTrade, HTTPResponse])
+    assert_type(client.list_tickers(raw=raw), Union[Iterator[Ticker], HTTPResponse])
+
+
+def ticker_symbols_or_none(client: RESTClient) -> Optional[List[str]]:
+    try:
+        return ticker_symbols(client)
+    except (AuthError, BadResponse):
+        return None
+
+
+def spread(q: CryptoQuote) -> Optional[float]:
+    assert_type(q.bid_price, Optional[float])
+    assert_type(q.ask_price, Optional[float])
+    assert_type(q.ask_size, Optional[float])
+    if q.ask_price is None or q.bid_price is None:
+        return None
+    return q.ask_price - q.bid_price
+
+
+def index_time_ms(v: IndexValue) -> Optional[int]:
+    assert_type(v.timestamp, Optional[int])
+    return v.timestamp
+
+
+def handle(msgs: List[WebSocketMessage]) -> None:
+    for m in msgs:
+        if isinstance(m, CryptoQuote):
+            spread(m)
+        elif isinstance(m, IndexValue):
+            index_time_ms(m)
+
+
+def make_ws_client() -> WebSocketClient:
+    return WebSocketClient(api_key="key", subscriptions=["XQ.BTC-USD"])
+
+
+def build_models() -> List[object]:
+    # Model constructors accept their fields as keywords.
+    quote = CryptoQuote(pair="BTC-USD", bid_price=33052.79, ask_size=0.601)
+    value = IndexValue(ticker="I:SPX", value=3988.5, timestamp=1678220098130)
+    trade = LastTrade(ticker="AAPL", sequence_number=3135876)
+    return [quote, value, trade]
+
+
+def written_for_earlier_releases(client: RESTClient, raw: bool) -> None:
+    # Code written when every REST method returned Union[Model, HTTPResponse]
+    # narrows the result itself. It must keep type-checking.
+    trade = client.get_last_trade("AAPL")
+    if isinstance(trade, LastTrade):
+        print(trade.price)
+    for t in client.list_tickers(cusip=37833100):
+        if isinstance(t, Ticker):
+            print(t.ticker)
+    resp = client.get_last_trade("AAPL", raw=True)
+    if isinstance(resp, HTTPResponse):
+        print(resp.status)
+    either: Union[LastTrade, HTTPResponse] = client.get_last_trade("AAPL", raw=raw)
+    tickers: Union[Iterator[Ticker], HTTPResponse] = client.list_tickers()
+    print(either, tickers)