btgsolutions-dataservices-python-client 4.8.1__tar.gz → 4.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 (58) hide show
  1. {btgsolutions_dataservices_python_client-4.8.1/btgsolutions_dataservices_python_client.egg-info → btgsolutions_dataservices_python_client-4.9.0}/PKG-INFO +110 -14
  2. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/README.md +862 -759
  3. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/__init__.py +2 -1
  4. btgsolutions_dataservices_python_client-4.9.0/btgsolutions_dataservices/book_by_order.py +588 -0
  5. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/config.py +13 -1
  6. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/__init__.py +2 -0
  7. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/bulk_data.py +3 -3
  8. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/dataservices_catalog.py +3 -6
  9. btgsolutions_dataservices_python_client-4.9.0/btgsolutions_dataservices/rest/market_events.py +149 -0
  10. btgsolutions_dataservices_python_client-4.9.0/btgsolutions_dataservices/rest/trades_and_book_events.py +286 -0
  11. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/websocket/__init__.py +2 -1
  12. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/websocket/market_data_websocket_client.py +100 -2
  13. btgsolutions_dataservices_python_client-4.9.0/btgsolutions_dataservices/websocket/realtime_book_events.py +434 -0
  14. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0/btgsolutions_dataservices_python_client.egg-info}/PKG-INFO +110 -14
  15. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices_python_client.egg-info/SOURCES.txt +9 -1
  16. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices_python_client.egg-info/requires.txt +1 -0
  17. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/requirements.txt +2 -1
  18. btgsolutions_dataservices_python_client-4.9.0/tests/test_book_by_order.py +437 -0
  19. btgsolutions_dataservices_python_client-4.9.0/tests/test_market_data_websocket_client_book_events.py +129 -0
  20. btgsolutions_dataservices_python_client-4.9.0/tests/test_realtime_book_events.py +484 -0
  21. btgsolutions_dataservices_python_client-4.9.0/tests/test_trades_and_book_events.py +355 -0
  22. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/LICENSE +0 -0
  23. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/MANIFEST.in +0 -0
  24. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/exceptions.py +0 -0
  25. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/algohunter.py +0 -0
  26. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/alternative_data_catalog.py +0 -0
  27. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/alternative_data_companies.py +0 -0
  28. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/alternative_data_funds.py +0 -0
  29. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/alternative_data_macro_markets.py +0 -0
  30. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/alternative_data_metadata.py +0 -0
  31. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/alternative_data_ownership.py +0 -0
  32. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/alternative_data_people.py +0 -0
  33. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/authenticator.py +0 -0
  34. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/book_scope.py +0 -0
  35. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/broker_analytics.py +0 -0
  36. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/broker_reference.py +0 -0
  37. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/company_data.py +0 -0
  38. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/corporate_events.py +0 -0
  39. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/hfn.py +0 -0
  40. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/historical_candles.py +0 -0
  41. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/historical_candles_crypto.py +0 -0
  42. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/intraday_candles.py +0 -0
  43. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/intraday_tick_data.py +0 -0
  44. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/public_sources.py +0 -0
  45. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/quotes.py +0 -0
  46. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/reference_data.py +0 -0
  47. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/stock_loan.py +0 -0
  48. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/ticker_last_event.py +0 -0
  49. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/rest/ticker_last_event_polling.py +0 -0
  50. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/websocket/broker_analytics.py +0 -0
  51. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/websocket/hfn_websocket_client.py +0 -0
  52. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/websocket/market_data_feed.py +0 -0
  53. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices/websocket/websocket_default_functions.py +0 -0
  54. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices_python_client.egg-info/dependency_links.txt +0 -0
  55. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/btgsolutions_dataservices_python_client.egg-info/top_level.txt +0 -0
  56. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/pyproject.toml +0 -0
  57. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/setup.cfg +0 -0
  58. {btgsolutions_dataservices_python_client-4.8.1 → btgsolutions_dataservices_python_client-4.9.0}/setup.py +0 -0
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.1
2
2
  Name: btgsolutions_dataservices_python_client
3
- Version: 4.8.1
3
+ Version: 4.9.0
4
4
  Summary: Python package containing several classes and data for extracting and manipulating market and trading data.
5
5
  Home-page: https://github.com/BTG-Pactual-Solutions/btgsolutions-dataservices-python-client
6
6
  Author: BTG Solutions Data Services powered by BTG Pactual Solutions
@@ -12,14 +12,7 @@ Requires-Dist: websocket-client>=1.8.0
12
12
  Requires-Dist: PyJWT>=2.8.0
13
13
  Requires-Dist: requests>=2.32.3
14
14
  Requires-Dist: pyarrow>=17.0.0
15
- Dynamic: author
16
- Dynamic: description
17
- Dynamic: description-content-type
18
- Dynamic: home-page
19
- Dynamic: license-file
20
- Dynamic: requires-dist
21
- Dynamic: requires-python
22
- Dynamic: summary
15
+ Requires-Dist: sortedcontainers>=2.4.0
23
16
 
24
17
  # BTG Solutions - Data Services
25
18
 
@@ -203,6 +196,66 @@ ws.unsubscribe_top_brokers(tickers=['SNFF11'])
203
196
  # sleep(1)
204
197
  ```
205
198
 
199
+ ##### Book Events (order-by-order book)
200
+
201
+ The B3 order-by-order book (market-by-order) with the broker of each order: a `book_snapshot` of each subscribed ticker (every resting order, in priority order), then one `book_event` per order change. Realtime only, at most 10 tickers per connection, for `stocks`, `options` and `derivatives`.
202
+
203
+ ```python
204
+ import btgsolutions_dataservices as btg
205
+
206
+ ws = btg.MarketDataWebSocketClient(
207
+ api_key='YOUR_API_KEY',
208
+ data_type='book-events',
209
+ data_subtype='derivatives',
210
+ instruments=['WINZ26'],
211
+ )
212
+ ws.run(on_message=lambda message: print(message)) # book_snapshot, then book_event / book_status
213
+
214
+ ws.get_last_event('WINZ26') # current book of a subscribed ticker (a book_snapshot)
215
+
216
+ ## The following is optional to keep the program running in a .py file:
217
+ # from time import sleep
218
+ # while True:
219
+ # sleep(1)
220
+ ```
221
+
222
+ For `book-events`, messages are handled in a single thread (book changes must be applied in order), the server certificate is always verified, `run()` waits at most `connect_timeout` seconds (default 10) for the connection to open and a dropped connection only calls `on_close` (no automatic reconnection at this level).
223
+
224
+ ##### Realtime Book by Order
225
+
226
+ `RealtimeBookEvents` keeps each ticker's book in memory (`BookByOrder`) from the `book-events` stream and yields one entry per change, in the same shape as the historical `TradesAndBookEvents.get_book()` (book only, no trades).
227
+
228
+ ```python
229
+ import btgsolutions_dataservices as btg
230
+
231
+ books = btg.RealtimeBookEvents(api_key='YOUR_API_KEY', data_subtype='derivatives')
232
+
233
+ for kind, info in books.get_book(['WINZ26', 'WDOZ26'], view='mbo', n_levels=5):
234
+ if kind == 'book':
235
+ print(info['symbol'], info['bid'][:1], info['offer'][:1], info['order']['event_type'], info['order']['action'])
236
+ else:
237
+ print('status:', info) # suspect / ok / waiting_snapshot / resyncing / disconnected / reconnected / reconnect_failed
238
+
239
+ # books.book('WINZ26') is the whole BookByOrder, always up to date
240
+ ```
241
+
242
+ - `view='mbo'` (default): top `n_levels` orders per side as `(order_id, price, size, broker)`; `view='mbp'`: top price levels as `(price, total_size)`.
243
+ - `info['order']`: the order that changed (`order_id`, `side`, `price`, `size`, `broker`, `event_type`, `action`, `seq_num`, `rpt_seq`, `timestamp` = order entry time) plus `transact_time` (exchange time of the change), `end_of_event` (last change of an exchange event; always `True` on a snapshot) and `prev_size` (on a `CHANGE`).
244
+ - `info['queued']`: messages already waiting behind this one. Near 0, the loop keeps up; if it keeps growing, the code inside the loop is slower than the feed. The book in memory is always current, so skipping work on an entry never skips the event in the book:
245
+
246
+ ```python
247
+ if not info['order']['end_of_event']:
248
+ continue # mid exchange event: an intermediate book
249
+ if info['queued'] > 0:
250
+ continue # something newer is already queued
251
+ heavy_work(books.book('WINZ26'))
252
+ ```
253
+
254
+ - A gap in a ticker's `seq_num` yields `('status', {'status': 'resyncing', 'reason': 'seq_gap'})`, asks the server for the current book and skips that ticker's events until it comes.
255
+ - Connection drops yield `disconnected` (with the server's close code and reason when it sends one), then `reconnected` (every book comes again as a snapshot) or, after `max_reconnects` consecutive failures, `reconnect_failed` and the generator ends. `reconnect=False` ends the generator right after `disconnected`.
256
+ - `timeout=` stops after that many seconds without messages; `break` or `books.close()` (also from another thread) closes the connection.
257
+ - Orders without price (market orders in auctions) come with `price=None`, ahead of every price level. During auctions the book can be crossed (best bid >= best offer), as on the exchange.
258
+
206
259
  #### Intraday Candles
207
260
 
208
261
  ```python
@@ -349,12 +402,8 @@ bulk_data.get_data(ticker='DI1F18', date='2017-01-02', data_type='trades')
349
402
  # bulk_data.get_data(ticker='PETR4', date='2024-01-22', data_type='books')
350
403
  # bulk_data.get_data(ticker='VALE3', date='2024-04-01', data_type='trades-and-book-events')
351
404
  # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='instrument-status')
352
- # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='price-events')
353
- # bulk_data.get_data(ticker='AURE3T', date='2025-05-07', data_type='open-interest')
354
405
  # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='execution-summary')
355
406
  # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='execution-statistics')
356
- # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='auction-imbalance')
357
- # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='price-quantity-bands')
358
407
  ```
359
408
 
360
409
  ##### Get Data With Billing Headers
@@ -392,6 +441,53 @@ bulk_data.get_compressed_data(channel='98', date='2026-01-30', data_type='instru
392
441
  # bulk_data.get_compressed_data(channel='98', date='2026-01-30', data_type='snapshot')
393
442
  ```
394
443
 
444
+ #### Historical Book by Order
445
+
446
+ Rebuild the order-by-order book of a past day from the trades-and-book-events stream, as a generator of `(kind, info)` pairs: `"book"` for each book change (with the `bid`/`offer` after it and the `order` that changed) and `"trade"` for trades. The day is streamed in bounded chunks (`batch_size`), so memory stays low.
447
+
448
+ ```python
449
+ import btgsolutions_dataservices as btg
450
+
451
+ events = btg.TradesAndBookEvents(api_key='YOUR_API_KEY')
452
+
453
+ for kind, info in events.get_book(ticker='PETR4', date='2026-05-15', view='mbo', n_levels=5):
454
+ if kind == 'trade':
455
+ print('trade:', info)
456
+ else:
457
+ print('book:', info['bid'][:1], info['offer'][:1], info['order']['action'])
458
+
459
+ # only a time window (the book is still replayed from the start of the day):
460
+ for kind, info in events.get_book(
461
+ ticker='PETR4', date='2026-05-15',
462
+ boundary=[
463
+ {'field': 'timestamp', 'value': '2026-05-15 14:00:00', 'mode': 'after'},
464
+ {'field': 'timestamp', 'value': '2026-05-15 14:30:00', 'mode': 'until'},
465
+ ],
466
+ ):
467
+ ...
468
+ ```
469
+
470
+ #### Market Events
471
+
472
+ ##### Available Tickers
473
+
474
+ ```python
475
+ import btgsolutions_dataservices as btg
476
+ market_events = btg.MarketEvents(api_key='YOUR_API_KEY')
477
+ market_events.get_available_tickers(date='2026-09-17', data_type='price-events', prefix='PETR')
478
+ ```
479
+
480
+ ##### Get Data
481
+
482
+ ```python
483
+ import btgsolutions_dataservices as btg
484
+ market_events = btg.MarketEvents(api_key='YOUR_API_KEY')
485
+ market_events.get_data(ticker='PETR4', date='2026-09-17', data_type='price-events')
486
+ # market_events.get_data(ticker='AURE3T', date='2026-09-17', data_type='open-interest')
487
+ # market_events.get_data(ticker='PETR4', date='2026-09-17', data_type='auction-imbalance')
488
+ # market_events.get_data(ticker='PETR4', date='2026-09-17', data_type='price-quantity-bands')
489
+ ```
490
+
395
491
  ### Alternative Data
396
492
 
397
493
  #### High Frequency News Stream