v1.1.3 - Order book and trade history functions

 - Added `order_history` and `get_orderbook` to `SteemEngineToken` for getting both historic, and currently open trades.
 - Created new data objects `SETrade` and `SEOrder` to represent the data returned by get_orderbook and order_history
 - `ObjBase` now aliases `__repr__()` to `__str__()` for child classes.
 - Updated documentation to show the new methods and objects.

Author: Someguy123

docs/source/code/privex.steemengine.SteemEngineToken.SteemEngineToken.rst

@@ -19,11 +19,13 @@ SteemEngineToken
       ~SteemEngineToken.custom_beem
       ~SteemEngineToken.find_steem_tx
       ~SteemEngineToken.get_balances
+      ~SteemEngineToken.get_orderbook
       ~SteemEngineToken.get_token
       ~SteemEngineToken.get_token_balance
       ~SteemEngineToken.issue_token
       ~SteemEngineToken.list_tokens
       ~SteemEngineToken.list_transactions
+      ~SteemEngineToken.order_history
       ~SteemEngineToken.send_token
 
 

docs/source/code/privex.steemengine.objects.rst

@@ -17,6 +17,8 @@ Data Objects (Token/SEBalance etc.)
       ObjBase
       SEBalance
       SETransaction
+      SETrade
+      SEOrder
       Token
       TokenMetadata
 

docs/source/code/stubs/privex.steemengine.SteemEngineToken.SteemEngineToken.get_orderbook.rst

@@ -0,0 +1,6 @@
+SteemEngineToken.get\_orderbook
+===================================================================
+
+.. currentmodule:: privex.steemengine.SteemEngineToken
+
+.. automethod:: SteemEngineToken.get_orderbook

docs/source/code/stubs/privex.steemengine.SteemEngineToken.SteemEngineToken.order_history.rst

@@ -0,0 +1,6 @@
+SteemEngineToken.order\_history
+===================================================================
+
+.. currentmodule:: privex.steemengine.SteemEngineToken
+
+.. automethod:: SteemEngineToken.order_history

docs/source/code/stubs/privex.steemengine.objects.SEOrder.rst

@@ -0,0 +1,23 @@
+objects.SEOrder
+==================================
+
+.. currentmodule:: privex.steemengine.objects
+
+.. autoclass:: SEOrder
+
+   
+   .. automethod:: __init__
+
+   
+   .. rubric:: Methods
+
+   .. autosummary::
+   
+      ~SEOrder.__init__
+      ~SEOrder.from_list
+   
+   
+
+   
+   
+   

docs/source/code/stubs/privex.steemengine.objects.SETrade.rst

@@ -0,0 +1,23 @@
+objects.SETrade
+==================================
+
+.. currentmodule:: privex.steemengine.objects
+
+.. autoclass:: SETrade
+
+   
+   .. automethod:: __init__
+
+   
+   .. rubric:: Methods
+
+   .. autosummary::
+   
+      ~SETrade.__init__
+      ~SETrade.from_list
+   
+   
+
+   
+   
+   

privex/steemengine/SteemEngineToken.py

@@ -4,7 +4,7 @@
 from privex.jsonrpc import SteemEngineRPC
 from privex.steemengine import exceptions
 from privex.steemengine.SteemEngineHistory import SteemEngineHistory
-from privex.steemengine.objects import SEBalance, SETransaction, Token
+from privex.steemengine.objects import SEBalance, SETransaction, Token, SETrade, SEOrder
 from privex.helpers import empty
 
 log = logging.getLogger(__name__)
@@ -198,6 +198,73 @@ def list_tokens(self, limit=1000, offset=0) -> List[Token]:
             limit=limit, offset=offset
         )))
 
+    def order_history(self, symbol, limit=30, offset=0, indexes: List[dict] = None) -> List[SETrade]:
+        """
+        Get a list of recent Steem Engine orders for a given symbol.
+
+        **Example:**
+
+            >>> o = SteemEngineToken().order_history('ENG')
+            >>> o[0]
+            <SETrade type='buy' price='0.99' symbol='ENG' quantity='0.80405854'>
+            >>> o[0].timestamp
+            '2019-07-27 01:06:09'
+
+        :param str symbol: The symbol to get historic orders for
+        :param int limit: Amount of orders to retrieve
+        :param int offset: Offset selection by this many rows (for pagination)
+        :param list indexes: A list of dictionary indexes, e.g. ``[dict(descending=False, index='timestamp')]``
+        :return List[SETrade] orders: A list of :py:class:`.SETrade` objects
+        """
+        indexes = [dict(descending=False, index='timestamp')] if empty(indexes) else indexes
+        return list(SETrade.from_list(self.rpc.find(
+            contract='market',
+            table='tradesHistory',
+            query=dict(symbol=symbol),
+            indexes=indexes,
+            limit=limit, offset=offset
+        )))
+    
+    def get_orderbook(self, symbol, direction='buy', user=None, limit=200, offset=0,
+                      indexes: list = None) -> List[SEOrder]:
+        """
+        Get a list of open Steem Engine orders for a given symbol, by default will display ``'buy'`` orders unless
+        you set ``direction`` to ``'sell'``
+
+        **Example:**
+
+            >>> o = SteemEngineToken().get_orderbook('ENG', direction='sell')
+            >>> o[0]
+            <SEOrder account='someguy123' price='0.99' symbol='ENG' quantity='885.40249121'>
+            >>> str(o[0].timestamp)
+            '2019-07-26 10:46:18'
+
+
+        :param str symbol: The symbol to get the open orders for
+        :param int limit: Amount of orders to retrieve
+        :param int offset: Offset selection by this many rows (for pagination)
+        :param list indexes: A list of dictionary indexes, e.g. ``[dict(descending=False, index='timestamp')]``
+        :param str user: If ``None`` , get all orders, otherwise only get orders by this user. Default: ``None``
+        :param str direction: The direction of orders to get, either ``buy`` or ``sell`` Default: ``buy``
+        :return List[SEOrder] orders: A list of :py:class:`.SEOrder` objects
+        """
+        direction = direction.lower()
+        if direction not in ['buy', 'sell']:
+            raise AttributeError('get_orderbook direction must be either "buy" or "sell"')
+
+        indexes = [dict(descending=direction == 'sell', index='price')] if empty(indexes) else indexes
+
+        q = dict(symbol=symbol)
+        if not empty(user):
+            q['account'] = user
+        return list(SEOrder.from_list(self.rpc.find(
+            contract='market',
+            table=f'{direction.lower()}Book',
+            query=q,
+            indexes=indexes,
+            limit=limit, offset=offset
+        )))
+
     def find_steem_tx(self, tx_data: dict, last_blocks=15) -> dict:
         """
         Used internally to get the transaction ID after a Steem transaction has been broadcasted.

privex/steemengine/objects.py

@@ -1,8 +1,12 @@
 import json
+from datetime import datetime
 from typing import Union, List, Generator
 from decimal import Decimal
 from privex.helpers import empty
 
+AnyNum = Union[Decimal, float, str]
+
+
 class ObjBase:
     """
     A base class to be extended by data storage classes, allowing their attributes to be
@@ -50,6 +54,10 @@ def from_list(cls, obj_list: List[dict]):
         for tx in obj_list:
             yield cls(**tx)
 
+    def __repr__(self):
+        return self.__str__()
+
+
 class TokenMetadata(ObjBase):
     """
     Represents the ``metadata`` field on a token object on SteemEngine
@@ -132,7 +140,6 @@ def __str__(self):
         return f"<SETransaction symbol='{self.symbol}' sender='{self.sender}' to='{self.to}' quantity='{self.quantity}'>"
 
 
-
 class SEBalance(ObjBase):
     """
     Represents an account token balance on SteemEngine
@@ -150,4 +157,74 @@ def __str__(self):
         return f"<SEBalance account='{self.account}' symbol='{self.symbol}' balance='{self.balance}'>"
 
 
+class SETrade(ObjBase):
+    """
+    Represents a past trade on the SE market.
+
+    :ivar str symbol: The symbol this order is for
+    :ivar Decimal quantity: The amount of tokens being bought/sold
+    :ivar Decimal price: The price per token ( :py:attr:`.symbol` ) in STEEM
+    :ivar datetime timestamp: The date/time which the order was placed
+    :ivar str direction: The type of order as a string, either ``'buy'`` or ``'sell'``
+    :ivar str type: Alias for ``direction`` - either ``'buy'`` or ``'sell'``
+    """
+
+    def __init__(self, symbol: str, quantity: AnyNum, price: AnyNum, timestamp: int, volume: AnyNum,
+                 direction: str = None, **kwargs):
+
+        direction = kwargs.get('type') if not direction else direction
+        self.raw_data = {
+            **kwargs,
+            **dict(symbol=symbol, quantity=quantity, price=price, timestamp=timestamp,
+                   volume=volume, direction=direction)
+        }
+        self.volume = Decimal(volume)
+        self.price = Decimal(price)
+        self.quantity = Decimal(quantity)
+        self.timestamp = datetime.utcfromtimestamp(int(timestamp))
+        self.symbol = symbol.upper()
+        self.direction = self.type = direction.lower()
+        if self.type not in ['buy', 'sell']:
+            raise AttributeError('SEOrder.type must be either buy or sell')
+
+    def __str__(self):
+        return f"<SETrade type='{self.type}' price='{self.price}' symbol='{self.symbol}' quantity='{self.quantity}'>"
+
+
+class SEOrder(ObjBase):
+    """
+    Represents an open order on the SE market.
+
+    :ivar str symbol: The symbol this order is for
+    :ivar Decimal quantity: The amount of tokens being bought/sold
+    :ivar Decimal price: The price per token ( :py:attr:`.symbol` ) in STEEM
+    :ivar Decimal tokens_locked: The amount of STEEM locked into the order
+    :ivar Decimal tokensLocked: Alias of ``tokens_locked``
+    :ivar datetime timestamp: The date/time which the order was placed
+    :ivar datetime expiration: ?????
+    :ivar str account: The username of the person who placed the order
+    :ivar str txid: The transaction ID of the order
+    """
+    def __init__(self, symbol: str, quantity: AnyNum, price: AnyNum, timestamp: int, account: str, expiration: int,
+                 txid: str = None, tokens_locked: AnyNum = None, **kwargs):
+        txid = kwargs.get('txId') if not txid else txid
+        tokens_locked = kwargs.get('tokensLocked') if not tokens_locked else tokens_locked
+        self.raw_data = {
+            **kwargs,
+            **dict(symbol=symbol, quantity=quantity, price=price, timestamp=timestamp, account=account,
+                   tokens_locked=tokens_locked, expiration=expiration, txid=txid)
+        }
+        self.tokens_locked = self.tokensLocked = None if not tokens_locked else Decimal(tokens_locked)
+        self.price = Decimal(price)
+        self.quantity = Decimal(quantity)
+        self.timestamp = datetime.utcfromtimestamp(int(timestamp))
+        self.expiration = datetime.utcfromtimestamp(int(expiration))
+        self.symbol = symbol.upper()
+        self.account = str(account).lower()
+        self.txid = str(txid)
+
+        pass
+
+    def __str__(self):
+        return f"<SEOrder account='{self.account}' price='{self.price}' symbol='{self.symbol}' quantity='{self.quantity}'>"
 

setup.py

@@ -42,7 +42,7 @@
 setup(
     name='privex_steemengine',
 
-    version='1.1.0',
+    version='1.1.3',
 
     description='A small library for querying and interacting with the SteemEngine network (https://steem-engine.com)',
     long_description=long_description,