btgsolutions-dataservices-python-client 4.8.2__tar.gz → 4.9.1__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.2/btgsolutions_dataservices_python_client.egg-info → btgsolutions_dataservices_python_client-4.9.1}/PKG-INFO +121 -11
  2. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/README.md +891 -776
  3. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/__init__.py +2 -1
  4. btgsolutions_dataservices_python_client-4.9.1/btgsolutions_dataservices/book_by_order.py +588 -0
  5. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/config.py +13 -1
  6. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/__init__.py +1 -0
  7. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/book_scope.py +112 -59
  8. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/dataservices_catalog.py +33 -14
  9. btgsolutions_dataservices_python_client-4.9.1/btgsolutions_dataservices/rest/trades_and_book_events.py +286 -0
  10. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/__init__.py +2 -1
  11. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/market_data_websocket_client.py +100 -2
  12. btgsolutions_dataservices_python_client-4.9.1/btgsolutions_dataservices/websocket/realtime_book_events.py +434 -0
  13. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1/btgsolutions_dataservices_python_client.egg-info}/PKG-INFO +122 -12
  14. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/SOURCES.txt +8 -1
  15. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/requires.txt +4 -3
  16. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/requirements.txt +2 -1
  17. btgsolutions_dataservices_python_client-4.9.1/tests/test_book_by_order.py +437 -0
  18. btgsolutions_dataservices_python_client-4.9.1/tests/test_market_data_websocket_client_book_events.py +129 -0
  19. btgsolutions_dataservices_python_client-4.9.1/tests/test_realtime_book_events.py +484 -0
  20. btgsolutions_dataservices_python_client-4.9.1/tests/test_trades_and_book_events.py +355 -0
  21. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/LICENSE +0 -0
  22. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/MANIFEST.in +0 -0
  23. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/exceptions.py +0 -0
  24. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/algohunter.py +0 -0
  25. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_catalog.py +0 -0
  26. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_companies.py +0 -0
  27. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_funds.py +0 -0
  28. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_macro_markets.py +0 -0
  29. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_metadata.py +0 -0
  30. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_ownership.py +0 -0
  31. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/alternative_data_people.py +0 -0
  32. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/authenticator.py +0 -0
  33. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/broker_analytics.py +0 -0
  34. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/broker_reference.py +0 -0
  35. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/bulk_data.py +0 -0
  36. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/company_data.py +0 -0
  37. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/corporate_events.py +0 -0
  38. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/hfn.py +0 -0
  39. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/historical_candles.py +0 -0
  40. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/historical_candles_crypto.py +0 -0
  41. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/intraday_candles.py +0 -0
  42. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/intraday_tick_data.py +0 -0
  43. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/market_events.py +0 -0
  44. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/public_sources.py +0 -0
  45. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/quotes.py +0 -0
  46. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/reference_data.py +0 -0
  47. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/stock_loan.py +0 -0
  48. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/ticker_last_event.py +0 -0
  49. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/rest/ticker_last_event_polling.py +0 -0
  50. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/broker_analytics.py +0 -0
  51. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/hfn_websocket_client.py +0 -0
  52. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/market_data_feed.py +0 -0
  53. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices/websocket/websocket_default_functions.py +0 -0
  54. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/dependency_links.txt +0 -0
  55. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/btgsolutions_dataservices_python_client.egg-info/top_level.txt +0 -0
  56. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/pyproject.toml +0 -0
  57. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/setup.cfg +0 -0
  58. {btgsolutions_dataservices_python_client-4.8.2 → btgsolutions_dataservices_python_client-4.9.1}/setup.py +0 -0
@@ -1,17 +1,12 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: btgsolutions_dataservices_python_client
3
- Version: 4.8.2
3
+ Version: 4.9.1
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
7
7
  Requires-Python: >=3.9,<3.15
8
8
  Description-Content-Type: text/markdown
9
9
  License-File: LICENSE
10
- Requires-Dist: pandas>=2.2.2
11
- Requires-Dist: websocket-client>=1.8.0
12
- Requires-Dist: PyJWT>=2.8.0
13
- Requires-Dist: requests>=2.32.3
14
- Requires-Dist: pyarrow>=17.0.0
15
10
 
16
11
  # BTG Solutions - Data Services
17
12
 
@@ -195,6 +190,66 @@ ws.unsubscribe_top_brokers(tickers=['SNFF11'])
195
190
  # sleep(1)
196
191
  ```
197
192
 
193
+ ##### Book Events (order-by-order book)
194
+
195
+ 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`.
196
+
197
+ ```python
198
+ import btgsolutions_dataservices as btg
199
+
200
+ ws = btg.MarketDataWebSocketClient(
201
+ api_key='YOUR_API_KEY',
202
+ data_type='book-events',
203
+ data_subtype='derivatives',
204
+ instruments=['WINZ26'],
205
+ )
206
+ ws.run(on_message=lambda message: print(message)) # book_snapshot, then book_event / book_status
207
+
208
+ ws.get_last_event('WINZ26') # current book of a subscribed ticker (a book_snapshot)
209
+
210
+ ## The following is optional to keep the program running in a .py file:
211
+ # from time import sleep
212
+ # while True:
213
+ # sleep(1)
214
+ ```
215
+
216
+ 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).
217
+
218
+ ##### Realtime Book by Order
219
+
220
+ `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).
221
+
222
+ ```python
223
+ import btgsolutions_dataservices as btg
224
+
225
+ books = btg.RealtimeBookEvents(api_key='YOUR_API_KEY', data_subtype='derivatives')
226
+
227
+ for kind, info in books.get_book(['WINZ26', 'WDOZ26'], view='mbo', n_levels=5):
228
+ if kind == 'book':
229
+ print(info['symbol'], info['bid'][:1], info['offer'][:1], info['order']['event_type'], info['order']['action'])
230
+ else:
231
+ print('status:', info) # suspect / ok / waiting_snapshot / resyncing / disconnected / reconnected / reconnect_failed
232
+
233
+ # books.book('WINZ26') is the whole BookByOrder, always up to date
234
+ ```
235
+
236
+ - `view='mbo'` (default): top `n_levels` orders per side as `(order_id, price, size, broker)`; `view='mbp'`: top price levels as `(price, total_size)`.
237
+ - `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`).
238
+ - `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:
239
+
240
+ ```python
241
+ if not info['order']['end_of_event']:
242
+ continue # mid exchange event: an intermediate book
243
+ if info['queued'] > 0:
244
+ continue # something newer is already queued
245
+ heavy_work(books.book('WINZ26'))
246
+ ```
247
+
248
+ - 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.
249
+ - 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`.
250
+ - `timeout=` stops after that many seconds without messages; `break` or `books.close()` (also from another thread) closes the connection.
251
+ - 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.
252
+
198
253
  #### Intraday Candles
199
254
 
200
255
  ```python
@@ -380,6 +435,32 @@ bulk_data.get_compressed_data(channel='98', date='2026-01-30', data_type='instru
380
435
  # bulk_data.get_compressed_data(channel='98', date='2026-01-30', data_type='snapshot')
381
436
  ```
382
437
 
438
+ #### Historical Book by Order
439
+
440
+ 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.
441
+
442
+ ```python
443
+ import btgsolutions_dataservices as btg
444
+
445
+ events = btg.TradesAndBookEvents(api_key='YOUR_API_KEY')
446
+
447
+ for kind, info in events.get_book(ticker='PETR4', date='2026-05-15', view='mbo', n_levels=5):
448
+ if kind == 'trade':
449
+ print('trade:', info)
450
+ else:
451
+ print('book:', info['bid'][:1], info['offer'][:1], info['order']['action'])
452
+
453
+ # only a time window (the book is still replayed from the start of the day):
454
+ for kind, info in events.get_book(
455
+ ticker='PETR4', date='2026-05-15',
456
+ boundary=[
457
+ {'field': 'timestamp', 'value': '2026-05-15 14:00:00', 'mode': 'after'},
458
+ {'field': 'timestamp', 'value': '2026-05-15 14:30:00', 'mode': 'until'},
459
+ ],
460
+ ):
461
+ ...
462
+ ```
463
+
383
464
  #### Market Events
384
465
 
385
466
  ##### Available Tickers
@@ -387,7 +468,7 @@ bulk_data.get_compressed_data(channel='98', date='2026-01-30', data_type='instru
387
468
  ```python
388
469
  import btgsolutions_dataservices as btg
389
470
  market_events = btg.MarketEvents(api_key='YOUR_API_KEY')
390
- market_events.get_available_tickers(date='2025-05-07', data_type='price-events', prefix='PETR')
471
+ market_events.get_available_tickers(date='2026-09-17', data_type='price-events', prefix='PETR')
391
472
  ```
392
473
 
393
474
  ##### Get Data
@@ -395,10 +476,10 @@ market_events.get_available_tickers(date='2025-05-07', data_type='price-events',
395
476
  ```python
396
477
  import btgsolutions_dataservices as btg
397
478
  market_events = btg.MarketEvents(api_key='YOUR_API_KEY')
398
- market_events.get_data(ticker='PETR4', date='2025-05-07', data_type='price-events')
399
- # market_events.get_data(ticker='AURE3T', date='2025-05-07', data_type='open-interest')
400
- # market_events.get_data(ticker='PETR4', date='2025-05-07', data_type='auction-imbalance')
401
- # market_events.get_data(ticker='PETR4', date='2025-05-07', data_type='price-quantity-bands')
479
+ market_events.get_data(ticker='PETR4', date='2026-09-17', data_type='price-events')
480
+ # market_events.get_data(ticker='AURE3T', date='2026-09-17', data_type='open-interest')
481
+ # market_events.get_data(ticker='PETR4', date='2026-09-17', data_type='auction-imbalance')
482
+ # market_events.get_data(ticker='PETR4', date='2026-09-17', data_type='price-quantity-bands')
402
483
  ```
403
484
 
404
485
  ### Alternative Data
@@ -761,6 +842,35 @@ single_file_result = book_scope.get(
761
842
  )
762
843
  ```
763
844
 
845
+ ##### Book Scope, NUAM Colombia / NUAM Chile / BIVA (Mexico) / BMV (Mexico)
846
+
847
+ These exchanges expose a single combined `book` dataset instead of B3's
848
+ `book_snapshot`/`book_incremental` split (every row already carries the full
849
+ bid/ask state), and take no `market_type` parameter.
850
+
851
+ ```python
852
+ import btgsolutions_dataservices as btg
853
+ book_scope = btg.BookScope(api_key='YOUR_API_KEY')
854
+
855
+ # NUAM Colombia
856
+ book_scope.get(
857
+ symbol='PFDAVIGRP',
858
+ market='nuam_colombia',
859
+ start_time='2026-05-28T14:12:00Z',
860
+ end_time='2026-05-28T14:15:00Z',
861
+ select=['trades', 'book'], # choose one or both; default is both
862
+ )
863
+
864
+ # NUAM Chile
865
+ book_scope.get(symbol='<TICKER>', market='nuam_chile', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
866
+
867
+ # BIVA (Mexico)
868
+ book_scope.get(symbol='<TICKER>', market='biva_mexico', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
869
+
870
+ # BMV (Mexico)
871
+ book_scope.get(symbol='<TICKER>', market='bmv_mexico', start_time='2026-05-28T14:12:00Z', end_time='2026-05-28T14:15:00Z')
872
+ ```
873
+
764
874
  #### Broker Analytics
765
875
 
766
876
  ```python