quantpad-data 0.8.5__tar.gz → 0.9.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/PKG-INFO +34 -3
  2. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/README.md +33 -2
  3. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/pyproject.toml +1 -1
  4. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/quantpad_data/__init__.py +7 -1
  5. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/quantpad_data/client.py +111 -1
  6. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_client.py +60 -0
  7. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/.gitignore +0 -0
  8. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/quantpad_data/cache.py +0 -0
  9. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/quantpad_data/errors.py +0 -0
  10. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/quantpad_data/lean.py +0 -0
  11. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/quantpad_data/memory.py +0 -0
  12. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/quantpad_data/py.typed +0 -0
  13. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/quantpad_data/rth.py +0 -0
  14. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/quantpad_data/v2.py +0 -0
  15. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/conftest.py +0 -0
  16. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_lean.py +0 -0
  17. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_message_encoding.py +0 -0
  18. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_packaging.py +0 -0
  19. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_refusal_hint.py +0 -0
  20. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_rth.py +0 -0
  21. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_v2.py +0 -0
  22. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_v2_cache.py +0 -0
  23. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_v2_gate.py +0 -0
  24. {quantpad_data-0.8.5 → quantpad_data-0.9.0}/tests/test_version.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: quantpad-data
3
- Version: 0.8.5
3
+ Version: 0.9.0
4
4
  Summary: Official Python client for the QuantPad market-data API
5
5
  Project-URL: Documentation, https://api.quantpad.ai/external/docs
6
6
  Author: QuantPad
@@ -88,8 +88,39 @@ levels 0-9. It is available for supported CME futures, individual CME
88
88
  options-on-futures contracts, and US equities, subject to `get_coverage()` and
89
89
  the plan lookback window (currently 30 days).
90
90
 
91
- This SDK intentionally exposes only bars, ticks, universe, coverage, and
92
- symbology. It does not proxy FRED or SEC EDGAR.
91
+ This SDK intentionally exposes only bars, ticks, universe, coverage,
92
+ symbology, and SEC insider transactions. It does not proxy FRED or SEC EDGAR.
93
+
94
+ ## SEC insider transactions
95
+
96
+ `get_insider_transactions` returns QuantPad's cleaned copy of the SEC's public
97
+ Form 3/4/5 filings: every transaction line since 2006, refreshed nightly. The
98
+ filings themselves are public domain; what the service adds is the cleaning:
99
+
100
+ - amendments (4/A) applied, so a corrected trade replaces the original;
101
+ - a trade filed separately by several members of a group (a fund, its general
102
+ partner, its principals) counted once;
103
+ - weighted-average price ranges and Rule 10b5-1 plans read from the footnotes;
104
+ - price typos flagged or corrected (a total value or a share count typed as
105
+ the price), checked within each security class (ADS vs ordinary shares);
106
+ - tickers that follow a company through renames.
107
+
108
+ ```python
109
+ # open-market buys and sells at one company
110
+ df = qpd.get_insider_transactions("NVDA", start="2020-01-01", signal=True)
111
+
112
+ # everything one insider filed, at every company
113
+ df = qpd.get_insider_transactions(owner_cik=1214156)
114
+
115
+ # market-wide open-market purchases (fetched a year at a time)
116
+ buys = qpd.get_insider_transactions(start="2025-01-01", end="2025-04-01",
117
+ codes="P", signal=True)
118
+ ```
119
+
120
+ `signal=True` keeps open-market purchases (`P`) and sales (`S`) that are
121
+ current, counted once, and sanely priced. For a backtest, use `accepted_at`
122
+ (UTC), or the end of `filed_date` where it is null, as the event time; never
123
+ `trans_date`, because insiders have two business days to file.
93
124
 
94
125
  ## Explicit addressing: `qpd.v2`
95
126
 
@@ -66,8 +66,39 @@ levels 0-9. It is available for supported CME futures, individual CME
66
66
  options-on-futures contracts, and US equities, subject to `get_coverage()` and
67
67
  the plan lookback window (currently 30 days).
68
68
 
69
- This SDK intentionally exposes only bars, ticks, universe, coverage, and
70
- symbology. It does not proxy FRED or SEC EDGAR.
69
+ This SDK intentionally exposes only bars, ticks, universe, coverage,
70
+ symbology, and SEC insider transactions. It does not proxy FRED or SEC EDGAR.
71
+
72
+ ## SEC insider transactions
73
+
74
+ `get_insider_transactions` returns QuantPad's cleaned copy of the SEC's public
75
+ Form 3/4/5 filings: every transaction line since 2006, refreshed nightly. The
76
+ filings themselves are public domain; what the service adds is the cleaning:
77
+
78
+ - amendments (4/A) applied, so a corrected trade replaces the original;
79
+ - a trade filed separately by several members of a group (a fund, its general
80
+ partner, its principals) counted once;
81
+ - weighted-average price ranges and Rule 10b5-1 plans read from the footnotes;
82
+ - price typos flagged or corrected (a total value or a share count typed as
83
+ the price), checked within each security class (ADS vs ordinary shares);
84
+ - tickers that follow a company through renames.
85
+
86
+ ```python
87
+ # open-market buys and sells at one company
88
+ df = qpd.get_insider_transactions("NVDA", start="2020-01-01", signal=True)
89
+
90
+ # everything one insider filed, at every company
91
+ df = qpd.get_insider_transactions(owner_cik=1214156)
92
+
93
+ # market-wide open-market purchases (fetched a year at a time)
94
+ buys = qpd.get_insider_transactions(start="2025-01-01", end="2025-04-01",
95
+ codes="P", signal=True)
96
+ ```
97
+
98
+ `signal=True` keeps open-market purchases (`P`) and sales (`S`) that are
99
+ current, counted once, and sanely priced. For a backtest, use `accepted_at`
100
+ (UTC), or the end of `filed_date` where it is null, as the event time; never
101
+ `trans_date`, because insiders have two business days to file.
71
102
 
72
103
  ## Explicit addressing: `qpd.v2`
73
104
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "quantpad-data"
7
- version = "0.8.5"
7
+ version = "0.9.0"
8
8
  description = "Official Python client for the QuantPad market-data API"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -89,6 +89,12 @@ def get_coverage(symbol: str):
89
89
  return _client().get_coverage(symbol)
90
90
 
91
91
 
92
+ def get_insider_transactions(ticker=None, **kwargs):
93
+ """SEC insider transactions (Forms 3/4/5); see
94
+ :meth:`Client.get_insider_transactions`."""
95
+ return _client().get_insider_transactions(ticker, **kwargs)
96
+
97
+
92
98
  def _iter_rth_windows_ms(start_ms: int, end_ms: int):
93
99
  try:
94
100
  import exchange_calendars as ec
@@ -218,7 +224,7 @@ __all__ = [
218
224
  "ROLL_ADJUST_MODES", "get_bars", "get_bars_with_retry", "get_ticks",
219
225
  "get_trades", "get_mbp1", "get_mbp10", "get_trades_rth", "get_mbp1_rth",
220
226
  "get_mbp10_rth", "get_spread_1m_rth", "symbology_resolve", "get_universe",
221
- "get_coverage", "iter_trades", "iter_mbp1", "iter_l1_df_chunks",
227
+ "get_coverage", "get_insider_transactions", "iter_trades", "iter_mbp1", "iter_l1_df_chunks",
222
228
  "iter_l1_trades_df_chunks", "iter_l1_mbp1_df_chunks", "cache", "lean",
223
229
  "v2", "Historical", "np", "pd", "pa",
224
230
  ]
@@ -87,7 +87,7 @@ V2_NOT_AVAILABLE = (
87
87
  "QuantPad support about /v2 access."
88
88
  )
89
89
 
90
- VERSION = "0.8.5"
90
+ VERSION = "0.9.0"
91
91
  USER_AGENT = f"quantpad-data-python/{VERSION}"
92
92
  TICK_SCHEMAS = (
93
93
  "trades", "mbp-1", "mbp-10", "cmbp-1", "tcbbo", "cbbo-1s",
@@ -209,6 +209,30 @@ def _prose_with_hint(error: dict) -> str:
209
209
  return str(message)
210
210
 
211
211
 
212
+ _INSIDER_DATE_COLS = (
213
+ "filed_date", "trans_date", "deemed_execution_date", "exercise_date", "expiration_date",
214
+ )
215
+ _INSIDER_NUMERIC_COLS = (
216
+ "shares", "price", "price_clean", "price_low", "price_high", "value",
217
+ "shares_owned_after", "conv_exercise_price", "underlying_shares",
218
+ )
219
+
220
+
221
+ def _insider_frame(rows: list[dict]) -> pd.DataFrame:
222
+ df = pd.DataFrame(rows)
223
+ if df.empty:
224
+ return df
225
+ for c in _INSIDER_DATE_COLS:
226
+ if c in df:
227
+ df[c] = pd.to_datetime(df[c], errors="coerce")
228
+ if "accepted_at" in df:
229
+ df["accepted_at"] = pd.to_datetime(df["accepted_at"], utc=True, errors="coerce")
230
+ for c in _INSIDER_NUMERIC_COLS:
231
+ if c in df:
232
+ df[c] = pd.to_numeric(df[c], errors="coerce")
233
+ return df
234
+
235
+
212
236
  class Client:
213
237
  def __init__(
214
238
  self,
@@ -541,3 +565,89 @@ class Client:
541
565
 
542
566
  def get_coverage(self, symbol: str) -> dict:
543
567
  return self._request("GET", "/v1/coverage", params={"symbol": symbol}).json()
568
+
569
+ def get_insider_transactions(
570
+ self,
571
+ ticker: str | None = None,
572
+ *,
573
+ issuer_cik: int | None = None,
574
+ owner_cik: int | None = None,
575
+ start: str | None = None,
576
+ end: str | None = None,
577
+ date_field: str = "filed",
578
+ codes: str | None = None,
579
+ kinds: str | None = None,
580
+ signal: bool = False,
581
+ include_superseded: bool = False,
582
+ include_duplicates: bool = False,
583
+ max_rows: int = 1_000_000,
584
+ ) -> pd.DataFrame:
585
+ """SEC insider transactions (Forms 3/4/5), one row per transaction line.
586
+
587
+ QuantPad's cleaned copy of the SEC's public filings, every line since
588
+ 2006, refreshed nightly: amendments applied, a trade filed by several
589
+ members of a group counted once, weighted-average price ranges and
590
+ 10b5-1 plans read from the footnotes, and price typos flagged.
591
+
592
+ Examples::
593
+
594
+ client.get_insider_transactions("NVDA", start="2020-01-01", signal=True)
595
+ client.get_insider_transactions(owner_cik=1214156)
596
+ client.get_insider_transactions(start="2025-01-01", end="2025-04-01",
597
+ codes="P", signal=True)
598
+
599
+ ``ticker`` follows the company through renames (by CIK). ``start``
600
+ is inclusive and ``end`` exclusive, on ``date_field`` ("filed", the
601
+ default, or "trans"). ``signal=True`` keeps open-market purchases
602
+ (P) and sales (S) that are current, counted once and sanely priced.
603
+ A market-wide pull (no ticker or CIK) needs ``start`` and ``end``
604
+ and is fetched a year at a time. Pages of up to 20,000 rows are
605
+ followed for you.
606
+
607
+ For a backtest, the event time is ``accepted_at`` (UTC), or the end
608
+ of ``filed_date`` where it is null. Never ``trans_date``: insiders
609
+ have two business days to file.
610
+ """
611
+ windows: list[tuple[str | None, str | None]] = [(start, end)]
612
+ if ticker is None and issuer_cik is None and owner_cik is None:
613
+ if not (start and end):
614
+ raise ValueError("a market-wide pull needs start and end")
615
+ s, e = pd.Timestamp(start), pd.Timestamp(end)
616
+ windows = []
617
+ while s < e:
618
+ n = min(s + pd.DateOffset(years=1), e)
619
+ windows.append((s.strftime("%Y-%m-%d"), n.strftime("%Y-%m-%d")))
620
+ s = n
621
+ rows: list[dict] = []
622
+ for ws, we in windows:
623
+ after = None
624
+ while len(rows) < max_rows:
625
+ params = {
626
+ "ticker": ticker, "issuer_cik": issuer_cik, "owner_cik": owner_cik,
627
+ "start": ws, "end": we, "date_field": date_field,
628
+ "codes": codes, "kinds": kinds,
629
+ "signal": str(bool(signal)).lower(),
630
+ "include_superseded": str(bool(include_superseded)).lower(),
631
+ "include_duplicates": str(bool(include_duplicates)).lower(),
632
+ "limit": min(20_000, max_rows - len(rows)),
633
+ "after": after,
634
+ }
635
+ page = self._request(
636
+ "GET", "/v1/insiders/transactions",
637
+ params={k: v for k, v in params.items() if v is not None},
638
+ ).json()
639
+ notes = page.get("footnotes") or {}
640
+ for r in page.get("rows") or []:
641
+ texts = notes.get(r.get("accession")) or {}
642
+ ids = r.pop("footnote_ids", None) or {}
643
+ r["footnotes"] = {
644
+ field: [texts[i] for i in fids if i in texts]
645
+ for field, fids in ids.items()
646
+ } or None
647
+ rows.append(r)
648
+ after = page.get("next_cursor")
649
+ if not after:
650
+ break
651
+ if len(rows) >= max_rows:
652
+ break
653
+ return _insider_frame(rows)
@@ -332,3 +332,63 @@ def test_get_mbp10_exposes_l2_schema_and_column_projection(monkeypatch):
332
332
  )
333
333
  assert captured["args"][:2] == ("ES.FUT", "mbp-10")
334
334
  assert captured["kwargs"] == {"columns": columns, "chunksize": 50_000}
335
+
336
+
337
+ def test_get_insider_transactions_pages_and_attaches_footnotes():
338
+ import json
339
+
340
+ page1 = {
341
+ "rows": [{"txn_key": "a:N:1", "accession": "a", "filed_date": "2026-11-16",
342
+ "accepted_at": "2026-11-16T21:05:00+00:00", "shares": "2700.0",
343
+ "price_clean": "63.917", "footnote_ids": {"price": ["F1"]}}],
344
+ "next_cursor": "2026-11-16|a:N:1",
345
+ "footnotes": {"a": {"F1": "weighted average, $63.50 to $64.20"}},
346
+ }
347
+ page2 = {"rows": [{"txn_key": "b:N:1", "accession": "b", "filed_date": "2026-11-17"}],
348
+ "next_cursor": None, "footnotes": {}}
349
+ session = FakeSession([response(body=json.dumps(page1).encode()),
350
+ response(body=json.dumps(page2).encode())])
351
+ client = Client(api_key="secret", session=session)
352
+ df = client.get_insider_transactions("pam", start="2026-11-01", signal=True)
353
+
354
+ assert list(df["txn_key"]) == ["a:N:1", "b:N:1"]
355
+ assert df.loc[0, "footnotes"] == {"price": ["weighted average, $63.50 to $64.20"]}
356
+ assert df.loc[0, "shares"] == 2700.0 and str(df["accepted_at"].dt.tz) == "UTC"
357
+ method, url, kwargs = session.calls[0]
358
+ assert method == "GET" and url.endswith("/v1/insiders/transactions")
359
+ assert kwargs["params"]["ticker"] == "pam" and kwargs["params"]["signal"] == "true"
360
+ assert "end" not in kwargs["params"] and "after" not in kwargs["params"]
361
+ assert session.calls[1][2]["params"]["after"] == "2026-11-16|a:N:1"
362
+ assert kwargs["headers"]["X-API-Key"] == "secret"
363
+
364
+
365
+ def test_get_insider_transactions_market_wide_needs_a_window_and_splits_by_year():
366
+ import json
367
+
368
+ client = Client(api_key="secret", session=FakeSession([]))
369
+ with pytest.raises(ValueError):
370
+ client.get_insider_transactions(codes="P")
371
+ empty = json.dumps({"rows": [], "next_cursor": None}).encode()
372
+ session = FakeSession([response(body=empty), response(body=empty)])
373
+ client = Client(api_key="secret", session=session)
374
+ df = client.get_insider_transactions(start="2024-01-01", end="2025-06-01", codes="P")
375
+ assert df.empty
376
+ windows = [(c[2]["params"]["start"], c[2]["params"]["end"]) for c in session.calls]
377
+ assert windows == [("2024-01-01", "2025-01-01"), ("2025-01-01", "2025-06-01")]
378
+
379
+
380
+ def test_module_level_insider_alias(monkeypatch):
381
+ captured = {}
382
+
383
+ class Stub:
384
+ def get_insider_transactions(self, ticker, **kwargs):
385
+ captured.update(ticker=ticker, kwargs=kwargs)
386
+ return "df"
387
+
388
+ monkeypatch.setattr(quantpad_data, "_client", lambda **kwargs: Stub())
389
+ assert quantpad_data.get_insider_transactions("NVDA", signal=True) == "df"
390
+ assert captured == {"ticker": "NVDA", "kwargs": {"signal": True}}
391
+
392
+
393
+ def test_insider_helper_is_public():
394
+ assert "get_insider_transactions" in quantpad_data.__all__
File without changes