docs(py): update docs.

nkaz001 · Aug 4, 2024 · e4ea86f · e4ea86f
1 parent bfb4447
commit e4ea86f
Show file tree

Hide file tree

Showing 11 changed files with 580 additions and 328 deletions.
diff --git a/docs/data.rst b/docs/data.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -266,6 +266,7 @@ Please see the `roadmap <https://github.com/nkaz001/hftbacktest/blob/master/ROAD
 
    Initialization <reference/initialization>
    Backtester <reference/backtester>
+   Constants <reference/constants>
    Statistics <reference/stats>
    Data Validation <reference/data_validation>
    Data Utilities <reference/data_utilities>

diff --git a/docs/reference/constants.rst b/docs/reference/constants.rst
@@ -0,0 +1,52 @@
+Constants
+=========
+
+.. autodata:: hftbacktest.types.EXCH_EVENT
+
+.. autodata:: hftbacktest.types.LOCAL_EVENT
+
+.. autodata:: hftbacktest.types.BUY_EVENT
+
+.. autodata:: hftbacktest.types.SELL_EVENT
+
+.. autodata:: hftbacktest.order.MARKET
+
+.. autodata:: hftbacktest.order.LIMIT
+
+.. autodata:: hftbacktest.order.BUY
+
+.. autodata:: hftbacktest.order.SELL
+
+.. autodata:: hftbacktest.order.NONE
+
+.. autodata:: hftbacktest.order.NEW
+
+.. autodata:: hftbacktest.order.EXPIRED
+
+.. autodata:: hftbacktest.order.FILLED
+
+.. autodata:: hftbacktest.order.PARTIALLY_FILLED
+
+.. autodata:: hftbacktest.order.CANCELED
+
+.. autodata:: hftbacktest.order.REJECTED
+
+.. autodata:: hftbacktest.order.GTC
+
+.. autodata:: hftbacktest.order.GTX
+
+.. autodata:: hftbacktest.order.FOK
+
+.. autodata:: hftbacktest.order.IOC
+
+.. autodata:: hftbacktest.types.ALL_ASSETS
+
+.. autodata:: hftbacktest.types.DEPTH_EVENT
+
+.. autodata:: hftbacktest.types.TRADE_EVENT
+
+.. autodata:: hftbacktest.types.DEPTH_CLEAR_EVENT
+
+.. autodata:: hftbacktest.types.DEPTH_SNAPSHOT_EVENT
+
+.. autodata:: hftbacktest.types.UNTIL_END_OF_DATA
diff --git a/docs/reference/data_validation.rst b/docs/reference/data_validation.rst
@@ -1,5 +1,5 @@
 Data Validation
 ===============
 
-.. automodule:: hftbacktest.data.validation
+.. automodule:: hftbacktest.data
    :members:
diff --git a/docs/reference/initialization.rst b/docs/reference/initialization.rst
@@ -6,4 +6,6 @@ Initialization
    :inherited-members:
    :member-order: bysource
 
-.. autofunction:: hftbacktest.MultiAssetMultiExchangeBacktest
+.. autofunction:: hftbacktest.HashMapMarketDepthBacktest
+
+.. autofunction:: hftbacktest.ROIVectorMarketDepthBacktest
diff --git a/docs/tutorials/Getting Started.ipynb b/docs/tutorials/Getting Started.ipynb
@@ -114,10 +114,8 @@
     ")\n",
     "\n",
     "# HftBacktest provides several types of built-in market depth implementations.\n",
-    "# HashMapMarketDepthMultiAssetMultiExchangeBacktest constructs a MultiAssetMultiExchangeBacktest\n",
-    "# using a HashMap-based market depth implementation.\n",
-    "# Another useful implementation is ROIVectorMarketDepth, which is utilized in\n",
-    "# ROIVectorMarketDepthMultiAssetMultiExchangeBacktest.\n",
+    "# HashMapMarketDepthBacktest constructs a Backtest using a HashMap-based market depth implementation.\n",
+    "# Another useful implementation is ROIVectorMarketDepth, which is utilized in ROIVectorMarketDepthBacktest.\n",
     "# Please find the details in the document below.\n",
     "hbt = HashMapMarketDepthBacktest([asset])"
    ]

diff --git a/examples/Getting Started.ipynb b/examples/Getting Started.ipynb
@@ -114,10 +114,8 @@
     ")\n",
     "\n",
     "# HftBacktest provides several types of built-in market depth implementations.\n",
-    "# HashMapMarketDepthMultiAssetMultiExchangeBacktest constructs a MultiAssetMultiExchangeBacktest\n",
-    "# using a HashMap-based market depth implementation.\n",
-    "# Another useful implementation is ROIVectorMarketDepth, which is utilized in\n",
-    "# ROIVectorMarketDepthMultiAssetMultiExchangeBacktest.\n",
+    "# HashMapMarketDepthBacktest constructs a Backtest using a HashMap-based market depth implementation.\n",
+    "# Another useful implementation is ROIVectorMarketDepth, which is utilized in ROIVectorMarketDepthBacktest.\n",
     "# Please find the details in the document below.\n",
     "hbt = HashMapMarketDepthBacktest([asset])"
    ]

diff --git a/py-hftbacktest/hftbacktest/binding.py b/py-hftbacktest/hftbacktest/binding.py
@@ -421,6 +421,12 @@ def values(self) -> Values:
                     break
                 # Do what you need with the order.
 
+        Alternatively, ``has_next`` returns ``True`` if there is a next element and ``False`` otherwise, while also
+        moving the iterator to the next element internally. ``get`` method then returns the element moved to by the
+        ``has_next`` method. Since ``has_next`` internally moves the iterator, it should not be used solely to check if
+        there is a next element.
+
+        **Example**
 
         .. code-block:: python
 
@@ -640,11 +646,12 @@ def last_trades(self, asset_no: uint64) -> EVENT_ARRAY:
 
     def clear_last_trades(self, asset_no: uint64) -> None:
         """
-        Clears the last trades occurring in the market from the buffer for :func:`trade`.
+        Clears the last trades occurring in the market from the buffer for :func:`last_trades`.
 
         Args:
-            asset_no: Asset number at which this command will be executed. If :const:`ALL_ASSETS`, all last trades in
-                      any assets will be cleared.
+            asset_no: Asset number at which this command will be executed.
+                      If :const:`ALL_ASSETS <hftbacktest.types.ALL_ASSETS>`,
+                      all last trades in any assets will be cleared.
         """
         hashmapbt_clear_last_trades(self.ptr, asset_no)
 
@@ -654,7 +661,8 @@ def orders(self, asset_no: uint64) -> OrderDict:
             asset_no: Asset number from which orders will be retrieved.
 
         Returns:
-            An order dictionary where the keys are order IDs and the corresponding values are :class:`Order`s.
+            An order dictionary where the keys are order IDs and the corresponding values are
+            :class:`Order <hftbacktest.order.Order>`.
         """
         return OrderDict_(hashmapbt_orders(self.ptr, asset_no))
 
@@ -677,17 +685,18 @@ def submit_buy_order(
                       exchange sides.
             price: Order price.
             qty: Quantity to buy.
-            time_in_force: Available options vary depending on the exchange model. See to the exchange model for
-                           details.
+            time_in_force: Available options vary depending on the exchange model. See to the exchange model for details.
+
+                * :const:`GTC <hftbacktest.order.GTC>`
+                * :const:`GTX <hftbacktest.order.GTX>`
+                * :const:`FOK <hftbacktest.order.FOK>`
+                * :const:`IOC <hftbacktest.order.IOC>`
 
-                * :const:`GTC`
-                * :const:`GTX`
-                * :const:`FOK`
-                * :const:`IOC`
             order_type: Available options vary depending on the exchange model. See to the exchange model for details.
 
-                * :const:`LIMIT`
-                * :const:`MARKET`
+                * :const:`LIMIT <hftbacktest.order.LIMIT>`
+                * :const:`MARKET <hftbacktest.order.MARKET>`
+
             wait: If `True`, wait until the order placement response is received.
 
         Returns:
@@ -715,18 +724,19 @@ def submit_sell_order(
             order_id: The unique order ID; there should not be any existing order with the same ID on both local and
                       exchange sides.
             price: Order price.
-            qty: Quantity to buy.
-            time_in_force: Available options vary depending on the exchange model. See to the exchange model for
-                           details.
+            qty: Quantity to sell.
+            time_in_force: Available options vary depending on the exchange model. See to the exchange model for details.
+
+                * :const:`GTC <hftbacktest.order.GTC>`
+                * :const:`GTX <hftbacktest.order.GTX>`
+                * :const:`FOK <hftbacktest.order.FOK>`
+                * :const:`IOC <hftbacktest.order.IOC>`
 
-                * :const:`GTC`
-                * :const:`GTX`
-                * :const:`FOK`
-                * :const:`IOC`
             order_type: Available options vary depending on the exchange model. See to the exchange model for details.
 
-                * :const:`LIMIT`
-                * :const:`MARKET`
+                * :const:`LIMIT <hftbacktest.order.LIMIT>`
+                * :const:`MARKET <hftbacktest.order.MARKET>`
+
             wait: If `True`, wait until the order placement response is received.
 
         Returns:
@@ -754,12 +764,13 @@ def cancel(self, asset_no: uint64, order_id: uint64, wait: bool) -> int64:
 
     def clear_inactive_orders(self, asset_no: uint64) -> None:
         """
-        Clears inactive orders from the local order dictionary whose status is neither :const:`NEW` nor
-        :const:`PARTIALLY_FILLED`.
+        Clears inactive orders from the local order dictionary whose status is neither
+        :const:`NEW <hftbacktest.order.NEW>` nor :const:`PARTIALLY_FILLED <hftbacktest.order.PARTIALLY_FILLED>`.
 
         Args:
-            asset_no: Asset number at which this command will be executed. If :const:`ALL_ASSETS`, all inactive orders
-                      in any assets will be cleared.
+            asset_no: Asset number at which this command will be executed.
+                      If :const:`ALL_ASSETS <hftbacktest.types.ALL_ASSETS>`,
+                      all inactive orders in any assets will be cleared.
         """
         hashmapbt_clear_inactive_orders(self.ptr, asset_no)
 
@@ -1054,11 +1065,12 @@ def last_trades(self, asset_no: uint64) -> EVENT_ARRAY:
 
     def clear_last_trades(self, asset_no: uint64) -> None:
         """
-        Clears the last trades occurring in the market from the buffer for :func:`trade`.
+        Clears the last trades occurring in the market from the buffer for :func:`last_trades`.
 
         Args:
-            asset_no: Asset number at which this command will be executed. If :const:`ALL_ASSETS`, all last trades in
-                      any assets will be cleared.
+            asset_no: Asset number at which this command will be executed.
+                      If :const:`ALL_ASSETS <hftbacktest.types.ALL_ASSETS>`,
+                      all last trades in any assets will be cleared.
         """
         roivecbt_clear_last_trades(self.ptr, asset_no)
 
@@ -1068,7 +1080,8 @@ def orders(self, asset_no: uint64) -> OrderDict:
             asset_no: Asset number from which orders will be retrieved.
 
         Returns:
-            An order dictionary where the keys are order IDs and the corresponding values are :class:`Order`s.
+            An order dictionary where the keys are order IDs and the corresponding values are
+            :class:`Order <hftbacktest.order.Order>`.
         """
         return OrderDict_(roivecbt_orders(self.ptr, asset_no))
 
@@ -1091,17 +1104,18 @@ def submit_buy_order(
                       exchange sides.
             price: Order price.
             qty: Quantity to buy.
-            time_in_force: Available options vary depending on the exchange model. See to the exchange model for
-                           details.
+            time_in_force: Available options vary depending on the exchange model. See to the exchange model for details.
+
+                * :const:`GTC <hftbacktest.order.GTC>`
+                * :const:`GTX <hftbacktest.order.GTX>`
+                * :const:`FOK <hftbacktest.order.FOK>`
+                * :const:`IOC <hftbacktest.order.IOC>`
 
-                * :const:`GTC`
-                * :const:`GTX`
-                * :const:`FOK`
-                * :const:`IOC`
             order_type: Available options vary depending on the exchange model. See to the exchange model for details.
 
-                * :const:`LIMIT`
-                * :const:`MARKET`
+                * :const:`LIMIT <hftbacktest.order.LIMIT>`
+                * :const:`MARKET <hftbacktest.order.MARKET>`
+
             wait: If `True`, wait until the order placement response is received.
 
         Returns:
@@ -1129,18 +1143,19 @@ def submit_sell_order(
             order_id: The unique order ID; there should not be any existing order with the same ID on both local and
                       exchange sides.
             price: Order price.
-            qty: Quantity to buy.
-            time_in_force: Available options vary depending on the exchange model. See to the exchange model for
-                           details.
+            qty: Quantity to sell.
+            time_in_force: Available options vary depending on the exchange model. See to the exchange model for details.
+
+                * :const:`GTC <hftbacktest.order.GTC>`
+                * :const:`GTX <hftbacktest.order.GTX>`
+                * :const:`FOK <hftbacktest.order.FOK>`
+                * :const:`IOC <hftbacktest.order.IOC>`
 
-                * :const:`GTC`
-                * :const:`GTX`
-                * :const:`FOK`
-                * :const:`IOC`
             order_type: Available options vary depending on the exchange model. See to the exchange model for details.
 
-                * :const:`LIMIT`
-                * :const:`MARKET`
+                * :const:`LIMIT <hftbacktest.order.LIMIT>`
+                * :const:`MARKET <hftbacktest.order.MARKET>`
+
             wait: If `True`, wait until the order placement response is received.
 
         Returns:
@@ -1168,12 +1183,13 @@ def cancel(self, asset_no: uint64, order_id: uint64, wait: bool) -> int64:
 
     def clear_inactive_orders(self, asset_no: uint64) -> None:
         """
-        Clears inactive orders from the local order dictionary whose status is neither :const:`NEW` nor
-        :const:`PARTIALLY_FILLED`.
+        Clears inactive orders from the local order dictionary whose status is neither
+        :const:`NEW <hftbacktest.order.NEW>` nor :const:`PARTIALLY_FILLED <hftbacktest.order.PARTIALLY_FILLED>`.
 
         Args:
-            asset_no: Asset number at which this command will be executed. If :const:`ALL_ASSETS`, all inactive orders
-                      in any assets will be cleared.
+            asset_no: Asset number at which this command will be executed.
+                      If :const:`ALL_ASSETS <hftbacktest.types.ALL_ASSETS>`,
+                      all inactive orders in any assets will be cleared.
         """
         roivecbt_clear_inactive_orders(self.ptr, asset_no)
 

diff --git a/py-hftbacktest/hftbacktest/order.py b/py-hftbacktest/hftbacktest/order.py
@@ -9,22 +9,54 @@
 UNSUPPORTED = 255
 
 BUY = 1
+"""
+In the market depth event, this indicates the bid side; in the market trade event, 
+it indicates that the trade initiator is a buyer.
+"""
+
 SELL = -1
+"""
+In the market depth event, this indicates the ask side; in the market trade event, 
+it indicates that the trade initiator is a seller.
+"""
 
+#: NONE
 NONE = 0
+
+#: NEW
 NEW = 1
+
+#: EXPIRED
 EXPIRED = 2
+
+#: FILLED
 FILLED = 3
+
+#: CANCELED
 CANCELED = 4
+
+#: PARTIALLY_FILLED
 PARTIALLY_FILLED = 5
+
+#: REJECTED
 REJECTED = 6
 
-GTC = 0  # Good 'till cancel
-GTX = 1  # Post only
-FOK = 2  # Fill or kill
-IOC = 3  # Immediate or cancel
+#: Good 'till cancel
+GTC = 0
+
+#: Post only
+GTX = 1
+
+#: Fill or kill
+FOK = 2
 
+#: Immediate or cancel
+IOC = 3
+
+#: LIMIT
 LIMIT = 0
+
+#: MARKET
 MARKET = 1
 
 

diff --git a/py-hftbacktest/hftbacktest/stats/__init__.py b/py-hftbacktest/hftbacktest/stats/__init__.py
@@ -4,6 +4,7 @@
     LinearAssetRecord
 )
 from .metrics import (
+    Metric,
     Ret,
     AnnualRet,
     SR,
@@ -28,6 +29,7 @@
     'InverseAssetRecord',
     'LinearAssetRecord',
 
+    'Metric',
     'Ret',
     'AnnualRet',
     'SR',