itmatrix 1.0.0__py3-none-any.whl

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.
@@ -0,0 +1,633 @@
1
+ """Grouped handwritten resources for every non-internal /v2 operation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Awaitable, Callable, Mapping
6
+ from typing import Any, Literal
7
+ from urllib.parse import quote
8
+
9
+ from ._wire.rest_pb2 import (
10
+ OffExchangeActivityResponse,
11
+ OffExchangeCompositionResponse,
12
+ OffExchangeConcentrationResponse,
13
+ OffExchangeProfileResponse,
14
+ )
15
+ from .models import (
16
+ OffExchangeActivityRow,
17
+ OffExchangeCompositionRow,
18
+ OffExchangeConcentrationRow,
19
+ OffExchangeProfileRow,
20
+ PremiumData,
21
+ QueryValue,
22
+ Quote,
23
+ Result,
24
+ SymbolIdentity,
25
+ )
26
+
27
+ Requester = Callable[..., Awaitable[Result[Any]]]
28
+ Classification = Literal["professional", "non_professional"]
29
+ DarkpoolConditionCategory = Literal[
30
+ "regular_way",
31
+ "odd_lot",
32
+ "package_price",
33
+ "form_t",
34
+ "average_price",
35
+ "derivatively_priced",
36
+ "late_oos",
37
+ ]
38
+ DarkpoolSort = Literal[
39
+ "rank",
40
+ "off_exch_notional",
41
+ "off_exch_volume",
42
+ "share",
43
+ "trade_count",
44
+ "z20",
45
+ "z60",
46
+ "pctile_20",
47
+ "rel_print_max",
48
+ "accel_5_20",
49
+ ]
50
+ FundamentalsDataset = Literal[
51
+ "ratios",
52
+ "income",
53
+ "balance-sheet",
54
+ "float",
55
+ "short-interest",
56
+ "dividends",
57
+ "news",
58
+ ]
59
+ ImportFormat = Literal["jsonl", "csv"]
60
+
61
+
62
+ def _id(value: str) -> str:
63
+ return quote(value, safe="")
64
+
65
+
66
+ def _symbol(value: str) -> str:
67
+ return _id(value.upper())
68
+
69
+
70
+ class AccountResource:
71
+ def __init__(self, request: Requester) -> None:
72
+ self._request = request
73
+
74
+ async def classification(self) -> Result[Any]:
75
+ return await self._request("/v2/account/classification")
76
+
77
+ async def submit_classification(
78
+ self, classification: Classification
79
+ ) -> Result[Any]:
80
+ return await self._request(
81
+ "/v2/account/classification",
82
+ method="POST",
83
+ body={"classification": classification},
84
+ )
85
+
86
+ async def list_keys(self) -> Result[Any]:
87
+ return await self._request("/v2/account/keys")
88
+
89
+ async def create_key(self) -> Result[Any]:
90
+ return await self._request("/v2/account/keys", method="POST")
91
+
92
+ async def delete_key(self, key_id: str) -> Result[Any]:
93
+ return await self._request(f"/v2/account/keys/{_id(key_id)}", method="DELETE")
94
+
95
+ async def usage(self) -> Result[Any]:
96
+ return await self._request("/v2/account/usage")
97
+
98
+
99
+ class OffExchangeResource:
100
+ """Typed synthetic off-exchange analytics.
101
+
102
+ Every response carries freshness in ``meta`` (``session``,
103
+ ``latest_session``, ``as_of``, ``history_sessions``) and, when the result
104
+ was truncated to a page, an opaque ``meta.cursor`` to pass back as
105
+ ``cursor``. Empty ``data`` with a ``meta.note`` is an honest empty answer,
106
+ never a denial.
107
+
108
+ Individual prints, blocks, intraday cells and evidence snapshots are
109
+ app-only and are not representable through this resource. When the client
110
+ uses ``transport="protobuf"``, every method negotiates and decodes the
111
+ endpoint-specific public protobuf message automatically.
112
+ """
113
+
114
+ def __init__(self, request: Requester) -> None:
115
+ self._request = request
116
+
117
+ async def _get(
118
+ self, symbol: str, view: str, message_type: type, **options: QueryValue
119
+ ) -> Result[Any]:
120
+ return await self._request(
121
+ f"/v2/offexchange/{_symbol(symbol)}/{view}",
122
+ query=options,
123
+ message_type=message_type,
124
+ )
125
+
126
+ async def activity(
127
+ self, symbol: str, **options: QueryValue
128
+ ) -> Result[list[OffExchangeActivityRow] | OffExchangeActivityResponse]:
129
+ return await self._get(
130
+ symbol, "activity", OffExchangeActivityResponse, **options
131
+ )
132
+
133
+ async def concentration(
134
+ self, symbol: str, **options: QueryValue
135
+ ) -> Result[list[OffExchangeConcentrationRow] | OffExchangeConcentrationResponse]:
136
+ return await self._get(
137
+ symbol, "concentration", OffExchangeConcentrationResponse, **options
138
+ )
139
+
140
+ async def profile(
141
+ self, symbol: str, **options: QueryValue
142
+ ) -> Result[list[OffExchangeProfileRow] | OffExchangeProfileResponse]:
143
+ return await self._get(symbol, "profile", OffExchangeProfileResponse, **options)
144
+
145
+ async def composition(
146
+ self, symbol: str, **options: QueryValue
147
+ ) -> Result[list[OffExchangeCompositionRow] | OffExchangeCompositionResponse]:
148
+ return await self._get(
149
+ symbol, "composition", OffExchangeCompositionResponse, **options
150
+ )
151
+
152
+
153
+ # Compatibility name; it is the same safe resource and cannot call legacy
154
+ # /v2/darkpool evidence routes.
155
+ DarkpoolResource = OffExchangeResource
156
+
157
+
158
+ class EconomyResource:
159
+ def __init__(self, request: Requester) -> None:
160
+ self._request = request
161
+
162
+ async def rates(self, **options: QueryValue) -> Result[Any]:
163
+ return await self._request("/v2/economy/rates", query=options)
164
+
165
+ async def treasury_yields(self) -> Result[Any]:
166
+ return await self._request("/v2/economy/treasury-yields")
167
+
168
+
169
+ class FlowResource:
170
+ def __init__(self, request: Requester) -> None:
171
+ self._request = request
172
+
173
+ async def large_trades(
174
+ self,
175
+ *,
176
+ symbol: str | None = None,
177
+ min_premium_usd: float | None = None,
178
+ session: str | None = None,
179
+ limit: int | None = None,
180
+ ) -> Result[Any]:
181
+ """Newest grouped large trades, bounded to at most 100 events.
182
+
183
+ API requests must narrow the retained OPRA feed by ``symbol`` or
184
+ ``min_premium_usd``. The SDK checks this before making a request.
185
+ """
186
+ if symbol is None and min_premium_usd is None:
187
+ raise ValueError("large_trades requires symbol or min_premium_usd")
188
+ return await self._request(
189
+ "/v2/flow/large-trades",
190
+ query={
191
+ "symbol": symbol.upper() if symbol is not None else None,
192
+ "min_premium_usd": min_premium_usd,
193
+ "session": session,
194
+ "limit": limit,
195
+ },
196
+ )
197
+
198
+ async def premium(
199
+ self,
200
+ symbol: str,
201
+ *,
202
+ sessions: int | None = None,
203
+ bucket: Literal["5m"] | None = None,
204
+ min_premium_usd: float | None = None,
205
+ dte: Literal["all", "zero", "ex_zero"] | None = None,
206
+ to_ms: int | None = None,
207
+ ) -> Result[PremiumData]:
208
+ """Five-minute premium for retained detected large-trade legs.
209
+
210
+ This is an app-only Pro surface and requires a current CBOE
211
+ attestation. Coverage is explicitly partial unless the response says
212
+ otherwise; missing buckets are unknown, never synthetic zeroes.
213
+ """
214
+ return await self._request(
215
+ "/v2/flow/premium",
216
+ query={
217
+ "symbol": symbol.upper(),
218
+ "sessions": sessions,
219
+ "bucket": bucket,
220
+ "min_premium_usd": min_premium_usd,
221
+ "dte": dte,
222
+ "to_ms": to_ms,
223
+ },
224
+ )
225
+
226
+ async def cross_section(
227
+ self, symbol: str, *, session: str | None = None
228
+ ) -> Result[Any]:
229
+ return await self._request(
230
+ f"/v2/flow/{_symbol(symbol)}/cross-section",
231
+ query={"session": session},
232
+ )
233
+
234
+ async def prints(self, **options: QueryValue) -> Result[Any]:
235
+ """Every leg of every large trade seen on the bus this session.
236
+
237
+ In-memory and session-scoped: it starts empty each day and does not
238
+ backfill, so an empty ``data`` means "nothing yet today".
239
+ """
240
+ return await self._request("/v2/flow/prints", query=dict(options))
241
+
242
+ async def eod(
243
+ self,
244
+ *,
245
+ session: str,
246
+ symbol: str | None = None,
247
+ min_premium_usd: float | None = None,
248
+ from_ms: int | None = None,
249
+ to_ms: int | None = None,
250
+ right: Literal["call", "put"] | None = None,
251
+ expiry: str | None = None,
252
+ ) -> Result[Any]:
253
+ """Persisted large prints for one explicit completed session.
254
+
255
+ API requests must also narrow by ``symbol`` or
256
+ ``min_premium_usd``. The server returns at most 100 ranked prints.
257
+ """
258
+ if symbol is None and min_premium_usd is None:
259
+ raise ValueError("eod requires symbol or min_premium_usd")
260
+ return await self._request(
261
+ "/v2/flow/eod",
262
+ query={
263
+ "session": session,
264
+ "symbol": symbol.upper() if symbol is not None else None,
265
+ "min_premium_usd": min_premium_usd,
266
+ "from_ms": from_ms,
267
+ "to_ms": to_ms,
268
+ "right": right,
269
+ "expiry": expiry,
270
+ },
271
+ )
272
+
273
+ async def option_tape(self, contract: str, **options: QueryValue) -> Result[Any]:
274
+ """One contract's trade tape. ``contract`` is an OCC symbol."""
275
+ return await self._request(
276
+ f"/v2/options/{_symbol(contract)}/tape", query=dict(options)
277
+ )
278
+
279
+ async def option_footprint(
280
+ self, contract: str, **options: QueryValue
281
+ ) -> Result[Any]:
282
+ """One contract's volume-at-price footprint, bucketed by ``tf``."""
283
+ return await self._request(
284
+ f"/v2/options/{_symbol(contract)}/footprint", query=dict(options)
285
+ )
286
+
287
+
288
+ class VolResource:
289
+ """Our own implied-vol surface, out of the greeks engine (``site.vol``).
290
+
291
+ These are our numbers rather than a vendor's, which is why they are ours
292
+ to serve at all.
293
+ """
294
+
295
+ def __init__(self, request: Requester) -> None:
296
+ self._request = request
297
+
298
+ async def term(self, symbol: str) -> Result[Any]:
299
+ """ATM term structure for an underlying."""
300
+ return await self._request(f"/v2/options/{_symbol(symbol)}/vol/term")
301
+
302
+ async def surface(self, symbol: str) -> Result[Any]:
303
+ """The vol surface for an underlying."""
304
+ return await self._request(f"/v2/options/{_symbol(symbol)}/vol/surface")
305
+
306
+ async def greeks(self, contract: str, *, session: str | None = None) -> Result[Any]:
307
+ """Per-contract greeks. ``contract`` is an OCC symbol."""
308
+ return await self._request(
309
+ f"/v2/options/{_symbol(contract)}/greeks", query={"session": session}
310
+ )
311
+
312
+
313
+ class FundamentalsResource:
314
+ def __init__(self, request: Requester) -> None:
315
+ self._request = request
316
+
317
+ async def get(
318
+ self,
319
+ symbol: str,
320
+ dataset: FundamentalsDataset,
321
+ *,
322
+ timeframe: Literal["quarterly", "annual", "trailing_twelve_months"]
323
+ | None = None,
324
+ limit: int | None = None,
325
+ if_none_match: str | None = None,
326
+ timeout: float | None = None,
327
+ ) -> Result[Any]:
328
+ """One fundamentals dataset.
329
+
330
+ ``timeframe`` picks the statement period and ``limit`` the row count
331
+ (newest first, 1..=50) for the statement datasets; the backend ignores
332
+ both for the others. ``if_none_match`` revalidates a cached read — the
333
+ 304 comes back as ``Result(not_modified=True)``, which is cache
334
+ confirmation, not an empty dataset.
335
+ """
336
+ return await self._request(
337
+ f"/v2/fundamentals/{_symbol(symbol)}/{_id(dataset)}",
338
+ query={"timeframe": timeframe, "limit": limit},
339
+ if_none_match=if_none_match,
340
+ timeout=timeout,
341
+ )
342
+
343
+ async def digest(
344
+ self,
345
+ *,
346
+ kind: Literal["ticker", "brief"],
347
+ if_none_match: str | None = None,
348
+ timeout: float | None = None,
349
+ **options: QueryValue,
350
+ ) -> Result[Any]:
351
+ return await self._request(
352
+ "/v2/news/digest",
353
+ query={"kind": kind, **options},
354
+ if_none_match=if_none_match,
355
+ timeout=timeout,
356
+ )
357
+
358
+ async def news(
359
+ self,
360
+ *,
361
+ if_none_match: str | None = None,
362
+ timeout: float | None = None,
363
+ **options: QueryValue,
364
+ ) -> Result[Any]:
365
+ return await self._request(
366
+ "/v2/news",
367
+ query=options,
368
+ if_none_match=if_none_match,
369
+ timeout=timeout,
370
+ )
371
+
372
+
373
+ class JournalResource:
374
+ def __init__(self, request: Requester) -> None:
375
+ self._request = request
376
+
377
+ async def list_accounts(self) -> Result[Any]:
378
+ return await self._request("/v2/journal/accounts")
379
+
380
+ async def create_account(self, account: Mapping[str, Any]) -> Result[Any]:
381
+ return await self._request("/v2/journal/accounts", method="POST", body=account)
382
+
383
+ async def put_account(
384
+ self, account_id: str, account: Mapping[str, Any]
385
+ ) -> Result[Any]:
386
+ return await self._request(
387
+ f"/v2/journal/accounts/{_id(account_id)}",
388
+ method="PUT",
389
+ body=account,
390
+ )
391
+
392
+ async def patch_account(
393
+ self, account_id: str, patch: Mapping[str, Any]
394
+ ) -> Result[Any]:
395
+ return await self._request(
396
+ f"/v2/journal/accounts/{_id(account_id)}",
397
+ method="PATCH",
398
+ body=patch,
399
+ )
400
+
401
+ async def delete_account(self, account_id: str) -> Result[Any]:
402
+ return await self._request(
403
+ f"/v2/journal/accounts/{_id(account_id)}", method="DELETE"
404
+ )
405
+
406
+ async def list_trades(self) -> Result[Any]:
407
+ return await self._request("/v2/journal/trades")
408
+
409
+ async def create_trade(self, trade: Mapping[str, Any]) -> Result[Any]:
410
+ return await self._request("/v2/journal/trades", method="POST", body=trade)
411
+
412
+ async def put_trade(self, trade_id: str, trade: Mapping[str, Any]) -> Result[Any]:
413
+ return await self._request(
414
+ f"/v2/journal/trades/{_id(trade_id)}",
415
+ method="PUT",
416
+ body=trade,
417
+ )
418
+
419
+ async def patch_trade(self, trade_id: str, patch: Mapping[str, Any]) -> Result[Any]:
420
+ return await self._request(
421
+ f"/v2/journal/trades/{_id(trade_id)}",
422
+ method="PATCH",
423
+ body=patch,
424
+ )
425
+
426
+ async def delete_trade(self, trade_id: str) -> Result[Any]:
427
+ return await self._request(
428
+ f"/v2/journal/trades/{_id(trade_id)}", method="DELETE"
429
+ )
430
+
431
+ async def import_trades(
432
+ self,
433
+ contents: str,
434
+ *,
435
+ import_id: str,
436
+ format: ImportFormat = "jsonl",
437
+ ) -> Result[Any]:
438
+ return await self._request(
439
+ "/v2/journal/import",
440
+ method="POST",
441
+ query={"import_id": import_id, "format": format},
442
+ body=contents,
443
+ content_type="text/plain",
444
+ )
445
+
446
+
447
+ class MarketResource:
448
+ def __init__(self, request: Requester) -> None:
449
+ self._request = request
450
+
451
+ async def quotes(
452
+ self, symbols: str | list[str] | tuple[str, ...]
453
+ ) -> Result[list[Quote]]:
454
+ return await self._request("/v2/quotes", query={"symbols": symbols})
455
+
456
+ async def spot(self, symbol: str) -> Result[Any]:
457
+ return await self._request(f"/v2/symbols/{_symbol(symbol)}/spot")
458
+
459
+ async def option_bars(self, contract: str, **options: QueryValue) -> Result[Any]:
460
+ """OHLCV bars for a single option contract (OCC symbol).
461
+
462
+ The per-contract counterpart to the client's ``get_bars``, which is
463
+ underlying-scoped.
464
+ """
465
+ return await self._request(
466
+ f"/v2/options/{_symbol(contract)}/bars", query=dict(options)
467
+ )
468
+
469
+
470
+ class ReferenceResource:
471
+ def __init__(self, request: Requester) -> None:
472
+ self._request = request
473
+
474
+ async def list(
475
+ self, symbol_class: Literal["equity", "index"] | None = None
476
+ ) -> Result[Any]:
477
+ return await self._request("/v2/symbols", query={"class": symbol_class})
478
+
479
+ async def get(self, symbol: str) -> Result[Any]:
480
+ return await self._request(f"/v2/symbols/{_symbol(symbol)}")
481
+
482
+ async def lookup(self, query: str) -> Result[SymbolIdentity]:
483
+ return await self._request("/v2/symbols/lookup", query={"q": query})
484
+
485
+
486
+ class ScreenerResource:
487
+ def __init__(self, request: Requester) -> None:
488
+ self._request = request
489
+
490
+ async def movers(self, **options: QueryValue) -> Result[Any]:
491
+ return await self._request("/v2/screener/movers", query=options)
492
+
493
+ async def sectors(self, *, date: str | None = None) -> Result[Any]:
494
+ return await self._request("/v2/screener/sectors", query={"date": date})
495
+
496
+
497
+ class ProtocolResource:
498
+ def __init__(self, request: Requester) -> None:
499
+ self._request = request
500
+
501
+ async def descriptor(self, proto: int = 3) -> Result[Any]:
502
+ return await self._request("/v2/ws-protocol.json", query={"proto": proto})
503
+
504
+ async def websocket_schema(self) -> Result[str]:
505
+ return await self._request("/v2/ws-protocol.proto", accept="text/plain")
506
+
507
+ async def rest_schema(self) -> Result[str]:
508
+ return await self._request("/v2/rest-protocol.proto", accept="text/plain")
509
+
510
+
511
+ class InfoResource:
512
+ """Service discovery: liveness, readiness and the spec itself.
513
+
514
+ ``/healthz`` and ``/readyz`` are the only paths this SDK requests outside
515
+ ``/v2/`` (see ``_ROOT_PATHS`` in client.py, which allows exactly those two).
516
+ The API declares them ``public: true``, skipping the auth extractor, so
517
+ they answer before a key exists — which is the point of them.
518
+
519
+ ``ready()`` is the deploy contract, not a synonym for ``health()``: it
520
+ reports warm-up and is non-2xx while the process is still filling caches.
521
+ """
522
+
523
+ def __init__(self, request: Requester) -> None:
524
+ self._request = request
525
+
526
+ async def health(self) -> Result[Any]:
527
+ """Liveness. 200 once the process is serving at all."""
528
+ return await self._request("/healthz")
529
+
530
+ async def ready(self) -> Result[Any]:
531
+ """Readiness including warm-up — non-2xx means "not yet"."""
532
+ return await self._request("/readyz")
533
+
534
+ async def openapi(self) -> Result[Any]:
535
+ """The live OpenAPI document.
536
+
537
+ Its ``info.version``, operation set and ``x-exposure`` stamps are the
538
+ authority on what this deployment actually serves.
539
+ """
540
+ return await self._request("/v2/openapi.json")
541
+
542
+
543
+ class WatchlistsResource:
544
+ def __init__(self, request: Requester) -> None:
545
+ self._request = request
546
+
547
+ async def list(self) -> Result[Any]:
548
+ return await self._request("/v2/watchlists")
549
+
550
+ async def put(self, watchlist_id: str, watchlist: Mapping[str, Any]) -> Result[Any]:
551
+ return await self._request(
552
+ f"/v2/watchlists/{_id(watchlist_id)}",
553
+ method="PUT",
554
+ body=watchlist,
555
+ )
556
+
557
+ async def delete(self, watchlist_id: str) -> Result[Any]:
558
+ return await self._request(
559
+ f"/v2/watchlists/{_id(watchlist_id)}", method="DELETE"
560
+ )
561
+
562
+
563
+ SUPPORTED_OPERATIONS = frozenset(
564
+ {
565
+ "account_getClassification",
566
+ "account_submitClassification",
567
+ "account_listKeys",
568
+ "account_createKey",
569
+ "account_deleteKey",
570
+ "account_getUsage",
571
+ "bars_getBars",
572
+ "bars_getOptionBars",
573
+ "bars_getReplay",
574
+ "chain_getChain",
575
+ "chain_getExpirations",
576
+ "offexchange_getActivity",
577
+ "offexchange_getConcentration",
578
+ "offexchange_getProfile",
579
+ "offexchange_getComposition",
580
+ "economy_getRates",
581
+ "flow_getCrossSection",
582
+ "flow_getEod",
583
+ "flow_getLargeTrades",
584
+ "flow_getOptionFootprint",
585
+ "flow_getOptionTape",
586
+ "flow_getPremium",
587
+ "flow_getPrints",
588
+ "flow_getUoa",
589
+ "flow_getUoaEvent",
590
+ "economy_getTreasuryYields",
591
+ "fundamentals_getDataset",
592
+ "news_getNews",
593
+ "news_getDigest",
594
+ "gex_getGrid",
595
+ "gex_getHistory",
596
+ "gex_getReference",
597
+ "journal_listAccounts",
598
+ "journal_createAccount",
599
+ "journal_putAccount",
600
+ "journal_patchAccount",
601
+ "journal_deleteAccount",
602
+ "journal_importTrades",
603
+ "journal_listTrades",
604
+ "journal_createTrade",
605
+ "journal_putTrade",
606
+ "journal_patchTrade",
607
+ "journal_deleteTrade",
608
+ "market_getQuotes",
609
+ "market_getSpot",
610
+ "reference_listSymbols",
611
+ "reference_getSymbol",
612
+ "reference_lookupSymbol",
613
+ "studies_postAuthor",
614
+ "studies_postAuthorFeedback",
615
+ "screener_getMovers",
616
+ "screener_getSectors",
617
+ "stream_createTicket",
618
+ "stream_connectWs",
619
+ "stream_getProtocol",
620
+ "stream_getWsProtocolProto",
621
+ "stream_getRestProtocolProto",
622
+ "vol_getContractGreeks",
623
+ "vol_getSurface",
624
+ "vol_getTerm",
625
+ "watchlists_listWatchlists",
626
+ "watchlists_putWatchlist",
627
+ "watchlists_deleteWatchlist",
628
+ }
629
+ )
630
+
631
+ INTENTIONALLY_UNSUPPORTED_OPERATIONS = frozenset(
632
+ {"darkpool_getScanner", "darkpool_getDataset", "darkpool_getBreadth"}
633
+ )