Add aggregate trade iterator and documentation

Sam McHardy · Sam McHardy · commit 753c06fc7d70 · 2018-01-23T20:06:43.000+11:00
diff --git a/binance/client.py b/binance/client.py
@@ -63,6 +63,16 @@ class Client(object):
     ORDER_RESP_TYPE_RESULT = 'RESULT'
     ORDER_RESP_TYPE_FULL = 'FULL'
 
+    # For accessing the data returned by Client.aggregate_trades().
+    AGG_ID = 'a'
+    AGG_PRICE = 'p'
+    AGG_QUANTITY = 'q'
+    AGG_FIRST_TRADE_ID = 'f'
+    AGG_LAST_TRADE_ID = 'l'
+    AGG_TIME = 'T'
+    AGG_BUYER_MAKES = 'm'
+    AGG_BEST_MATCH = 'M'
+
     def __init__(self, api_key, api_secret, requests_params=None):
         """Binance API Client constructor
 
@@ -565,6 +575,77 @@ def get_aggregate_trades(self, **params):
         """
         return self._get('aggTrades', data=params)
 
+    def aggregate_trade_iter(self, symbol, start_str=None, last_id=None):
+        """Iterate over aggregate trade data from (start_time or last_id) to
+        the end of the history so far.
+
+        If start_time is specified, start with the first trade after
+        start_time. Meant to initialise a local cache of trade data.
+
+        If last_id is specified, start with the trade after it. This is meant
+        for updating a pre-existing local trade data cache.
+
+        Only allows start_str or last_id—not both. Not guaranteed to work
+        right if you're running more than one of these simultaneously. You
+        will probably hit your rate limit.
+
+        See dateparser docs for valid start and end string formats http://dateparser.readthedocs.io/en/latest/
+
+        If using offset strings for dates add "UTC" to date string e.g. "now UTC", "11 hours ago UTC"
+
+        :param symbol: Symbol string e.g. ETHBTC
+        :type symbol: str
+        :param start_str: Start date string in UTC format. The iterator will
+        return the first trade occurring later than this time.
+        :type start_str: str
+        :param last_id: aggregate trade ID of the last known aggregate trade.
+        Not a regular trade ID. See https://github.com/binance-exchange/binance-official-api-docs/blob/master/rest-api.md#compressedaggregate-trades-list.
+
+        :returns: an iterator of JSON objects, one per trade. The format of
+        each object is identical to Client.aggregate_trades().
+
+        :type last_id: int
+        """
+        if start_str is not None and last_id is not None:
+            raise ValueError(
+                'start_time and last_id may not be simultaneously specified.')
+
+        # If there's no last_id, get one.
+        if last_id is None:
+            # Without a last_id, we actually need the first trade.  Normally,
+            # we'd get rid of it. See the next loop.
+            if start_str is None:
+                trades = self.get_aggregate_trades(symbol=symbol, fromId=0)
+            else:
+                # It doesn't matter what the end time is, as long as it's less
+                # than a day and the result set contains at least one trade.
+                # A half a day should be fine.
+                start_ts = date_to_milliseconds(start_str)
+                trades = self.get_aggregate_trades(
+                    symbol=symbol,
+                    startTime=start_ts,
+                    endTime=start_ts + (1000 * 3600))
+            for t in trades:
+                yield t
+            last_id = trades[-1][self.AGG_ID]
+
+        while True:
+            # There is no need to wait between queries, to avoid hitting the
+            # rate limit. We're using blocking IO, and as long as we're the
+            # only thread running calls like this, Binance will automatically
+            # add the right delay time on their end, forcing us to wait for
+            # data. That really simplifies this function's job. Binance is
+            # fucking awesome.
+            trades = self.get_aggregate_trades(symbol=symbol, fromId=last_id)
+            # fromId=n returns a set starting with id n, but we already have
+            # that one. So get rid of the first item in the result set.
+            trades = trades[1:]
+            if len(trades) == 0:
+                return
+            for t in trades:
+                yield t
+            last_id = trades[-1][self.AGG_ID]
+
     def get_klines(self, **params):
         """Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.
 
diff --git a/docs/constants.rst b/docs/constants.rst
@@ -50,6 +50,16 @@ Binance requires specific string constants for Order Types, Order Side, Time in
     ORDER_RESP_TYPE_RESULT = 'RESULT'
     ORDER_RESP_TYPE_FULL = 'FULL'
 
+    # For accessing the data returned by Client.aggregate_trades().
+    AGG_ID             = 'a'
+    AGG_PRICE          = 'p'
+    AGG_QUANTITY       = 'q'
+    AGG_FIRST_TRADE_ID = 'f'
+    AGG_LAST_TRADE_ID  = 'l'
+    AGG_TIME           = 'T'
+    AGG_BUYER_MAKES    = 'm'
+    AGG_BEST_MATCH     = 'M'
+
 
 For Websocket Depth these are found on `binance.websockets.BinanceSocketManager`
 
diff --git a/docs/market_data.rst b/docs/market_data.rst
@@ -30,6 +30,29 @@ Market Data Endpoints
 
     trades = client.get_aggregate_trades(symbol='BNBBTC')
 
+`Aggregate Trade Iterator <binance.html#binance.client.Client.aggregate_trade_iter>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Iterate over aggregate trades for a symbol from a given date or a given order id.
+
+.. code:: python
+
+    agg_trades = client.aggregate_trade_iter(symbol='ETHBTC', start_str='30 minutes ago UTC')
+
+    # iterate over the trade iterator
+    for trade in agg_trades:
+        print(trade)
+        # do something with the trade data
+
+    # convert the iterator to a list
+    # note: generators can only be iterated over once so we need to call it again
+    agg_trades = client.aggregate_trade_iter(symbol='ETHBTC', '30 minutes ago UTC')
+    agg_trade_list = list(agg_trades)
+
+    # example using last_id value
+    agg_trades = client.aggregate_trade_iter(symbol='ETHBTC', last_id=23380478)
+    agg_trade_list = list(agg_trades)
+
 
 `Get Kline/Candlesticks <binance.html#binance.client.Client.get_klines>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
