1.103.1

Author: cjdsellers

README.md

@@ -107,6 +107,10 @@ The package is tested against Python 3.7 - 3.9 on both Linux and MacOS.
 We recommend users setup a virtual environment to isolate the dependencies, and run the platform
 with the latest stable version of Python.
 
+`pyenv` is the recommended tool for handling Python installations and virtual environments.
+
+> https://github.com/pyenv/pyenv
+
 Installation for Unix-like systems can be achieved through _one_ of the following options;
 
 #### From PyPI
@@ -143,9 +147,17 @@ Installation from source requires Cython to compile the Python C extensions.
         cd nautilus_trader
         pip install .
 
+## Examples
+
+Examples of both backtest and live trading launch scripts are available in the `examples` directory.
+These can run through PyCharm, or by running:
+
+    python <name_of_script>.py
+
 ## Data Types
 
-The following data types can be requested, and also subscribed to as streams.
+The following market data types can be requested historically, and also subscribed to as live streams
+when available from an exchange/broker, and implemented in an integrations adapter.
 
 - `Instrument`
 - `OrderBook` (L1, L2 and L3 if available. Streaming or interval snapshots)
@@ -229,6 +241,11 @@ exchanges.
 For development we recommend using the PyCharm _Professional_ edition IDE, as it interprets Cython
 syntax. Alternatively, you could use Visual Studio Code with a Cython extension.
 
+`pyenv` is the recommended tool for handling Python installations and virtual environments.
+
+> https://github.com/pyenv/pyenv
+
+
 `poetry` is the preferred tool for handling all Python package and dev dependencies.
 
 > https://python-poetry.org/
@@ -242,22 +259,22 @@ at commit.
 
 The following steps are for Unix-like systems, and only need to be completed once.
 
-1. Install the `pre-commit` package by running:
-
-        pip install pre-commit
-
-2. Install the Cython package by running:
+1. Install the Cython package by running:
 
         pip install -U Cython==3.0a6
 
-3. Install `poetry` by running:
+2. Install `poetry` by running:
 
         curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
 
-4. Then install all Python package dependencies, and compile the C extensions by running:
+3. Then install all Python package dependencies, and compile the C extensions by running:
 
         poetry install
 
+4. Install the `pre-commit` package by running:
+
+        pip install pre-commit
+
 5. Setup the `pre-commit` hook which will then run automatically at commit by running:
 
         pre-commit run --all-files

build.py

@@ -1,7 +1,7 @@
 import itertools
 import os
-import platform
 from pathlib import Path
+import platform
 import shutil
 from typing import List
 
@@ -12,7 +12,6 @@
 from setuptools import Distribution
 from setuptools import Extension
 
-
 # If DEBUG mode is enabled, skip compiler optimizations (TODO: implement)
 DEBUG_MODE = bool(os.getenv("DEBUG_MODE", ""))
 # If PROFILING mode is enabled, include traces necessary for coverage and profiling

docs/source/api_reference/common.rst

@@ -67,6 +67,15 @@ Logging
    :members:
    :member-order: bysource
 
+Queue
+-----
+
+.. automodule:: nautilus_trader.common.queue
+   :show-inheritance:
+   :inherited-members:
+   :members:
+   :member-order: bysource
+
 Timer
 -----
 

docs/source/developer_guide/coding_standards.rst

@@ -9,18 +9,18 @@ Code Style
 
 We philosophically agree with the ``Black`` formatting style, however it does not
 currently run over Cython code. So you could say we are "handcrafting towards"
-``Blacks`` stylistic conventions.
+``Black``s stylistic conventions.
 
 The current codebase can be used as a guide for formatting guidance.
 
-- For longer lines of code, and when passing more than a couple of arguments
+1- For longer lines of code, and when passing more than a couple of arguments
 it's common to take a new line which aligns at the next logical indent (rather
 than attempting a hanging alignment off an opening parenthesis).
 
-- The closing parenthesis should be located on a new line, aligned at the logical
+2- The closing parenthesis should be located on a new line, aligned at the logical
 indent.
 
-- Also ensure multiple hanging parameters or arguments end with a comma::
+3- Also ensure multiple hanging parameters or arguments end with a comma::
 
     LongCodeLine(
         some_arg1,

docs/source/developer_guide/environment.rst

@@ -1,7 +1,7 @@
 Environment
 ===========
 
-For development we recommend using the PyCharm _Professional_ edition IDE, as it
+For development we recommend using the PyCharm `Professional` edition IDE, as it
 interprets Cython syntax. Alternatively, you could use Visual Studio Code with
 a Cython extension.
 
@@ -18,29 +18,29 @@ Setup
 -----
 The following steps are for Unix-like systems, and only need to be completed once.
 
-1. Install ``pre-commit`` by running:
+1. Install ``pre-commit`` by running::
 
         pip install pre-commit
 
 2. Install the Cython package by running:
 
         pip install -U Cython==3.0a6
 
-3. Install ``poetry`` by running:
+3. Install ``poetry`` by running::
 
         curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
 
-4. Then install all Python package dependencies, and compile the C extensions by running:
+4. Then install all Python package dependencies, and compile the C extensions by running::
 
         poetry install
 
-5. Setup the ``pre-commit`` hook which will then run automatically at commit by running:
+5. Setup the ``pre-commit`` hook which will then run automatically at commit by running::
 
         pre-commit run --all-files
 
 Builds
 ------
 
-Following any changes to ``.pyx`` or ``.pxd`` files, you can re-compile by running:
+Following any changes to ``.pyx`` or ``.pxd`` files, you can re-compile by running::
 
     python build.py

docs/source/developer_guide/overview.rst

@@ -0,0 +1,38 @@
+Overview
+========
+
+Welcome to the developer guide for NautilusTrader!
+
+Here you will find information related to developing and extending the NautilusTrader
+codebase. These guides will assist you in both adding functionality for your own
+trading operation, and/or acting as a guide to assist with valuable contributions.
+
+We believe in using the right tool for the job. The overall design philosophy is
+to fully utilize the high level power of Python, with its rich eco-system of
+frameworks and libraries, whilst overcoming some of its inherent shortcomings in
+performance and lack of built in type safety (with it being an interpreted
+dynamic language).
+
+One of the advantages of Cython is that we don't have to concern ourselves with
+memory safety, as that is handled by its C code generator during the 'cythonization'
+step of the build. So we get the best of both worlds - with Pythons clean straight
+forward syntax, and a lot of potential to extract several orders of magnitude
+greater runtime performance through compiled C dynamic libraries.
+
+The main development and runtime environment we are working in is of course Python.
+However with the introduction of Cython syntax throughout the production codebase
+in ``.pyx`` and ``.pxd`` files - it's important to be aware of how the CPython
+implementation of Python interacts with the underlying CPython API, and the
+NautilusTrader C extension modules which Cython produces.
+
+We recommend a thorough review of the Cython documentation to familiarize yourself
+with some of its core concepts, and where C typing is being introduced.
+
+> https://cython.org
+
+Its not necessary to become a C language expert, however how Cython C syntax is
+used in function and method definitions, in local code blocks, and the common
+primitive C types and how these map to their corresponding ``PyObject`` types -
+should be well understood.
+
+**work in progress**

docs/source/developer_guide/testing.rst

@@ -49,7 +49,7 @@ Code coverage output is generated using ``coverage`` and reported using ``codeco
 High test coverage is a goal for the project however not at the expense of
 appropriate error handling, or causing "test induced damage" to the architecture.
 
-There are currently areas of the codebase which are 'impossible' to test unless
+There are currently areas of the codebase which are `impossible` to test unless
 there is a change to the production code. For example the last condition check
 of an if-else block which would catch an unrecognized value, these should be
 left in place in case there is a change to the production code - which these

docs/source/getting_started/installation.rst

@@ -51,7 +51,7 @@ Installation from source requires Cython to compile the Python C extensions.
 
         pip install -U git+https://github.com/nautechsystems/nautilus_trader
 
-    **Or** clone the source with ``git``, and install from the projects root directory by running::
+**Or** clone the source with ``git``, and install from the projects root directory by running::
 
         git clone https://github.com/nautechsystems/nautilus_trader
         cd nautilus_trader

docs/source/index.rst

@@ -140,6 +140,7 @@ Index
     :caption: Developer Guide
     :hidden:
 
+    developer_guide/overview
     developer_guide/environment
     developer_guide/coding_standards
     developer_guide/testing

examples/backtest/crypto_ema_cross_ethusdt_trade_ticks.py

@@ -15,10 +15,14 @@
 # -------------------------------------------------------------------------------------------------
 
 from decimal import Decimal
+import pathlib
+import sys
 
 import ccxt
 import pandas as pd
 
+sys.path.insert(0, str(pathlib.Path(__file__).parents[2]))  # Allows relative imports from examples
+
 from examples.strategies.ema_cross_simple import EMACross
 from nautilus_trader.adapters.ccxt.providers import CCXTInstrumentProvider
 from nautilus_trader.backtest.data_container import BacktestDataContainer

examples/backtest/fx_ema_cross_audusd_bars_from_ticks.py

@@ -16,9 +16,13 @@
 
 from decimal import Decimal
 import os
+import pathlib
+import sys
 
 import pandas as pd
 
+sys.path.insert(0, str(pathlib.Path(__file__).parents[2]))  # Allows relative imports from examples
+
 from examples.strategies.ema_cross_simple import EMACross
 from nautilus_trader.backtest.data_container import BacktestDataContainer
 from nautilus_trader.backtest.engine import BacktestEngine

examples/backtest/fx_ema_cross_audusd_ticks.py

@@ -16,9 +16,13 @@
 
 from decimal import Decimal
 import os
+import pathlib
+import sys
 
 import pandas as pd
 
+sys.path.insert(0, str(pathlib.Path(__file__).parents[2]))  # Allows relative imports from examples
+
 from examples.strategies.ema_cross_simple import EMACross
 from nautilus_trader.backtest.data_container import BacktestDataContainer
 from nautilus_trader.backtest.engine import BacktestEngine

examples/backtest/fx_ema_cross_gbpusd_bars.py

@@ -16,9 +16,13 @@
 
 from decimal import Decimal
 import os
+import pathlib
+import sys
 
 import pandas as pd
 
+sys.path.insert(0, str(pathlib.Path(__file__).parents[2]))  # Allows relative imports from examples
+
 from examples.strategies.ema_cross_simple import EMACross
 from nautilus_trader.backtest.data_container import BacktestDataContainer
 from nautilus_trader.backtest.engine import BacktestEngine

examples/backtest/fx_market_maker_gbpusd_bars.py

@@ -14,12 +14,15 @@
 #  limitations under the License.
 # -------------------------------------------------------------------------------------------------
 
-from datetime import datetime
 from decimal import Decimal
 import os
+import pathlib
+import sys
 
 import pandas as pd
 
+sys.path.insert(0, str(pathlib.Path(__file__).parents[2]))  # Allows relative imports from examples
+
 from examples.strategies.volatility_market_maker import VolatilityMarketMaker
 from nautilus_trader.backtest.data_container import BacktestDataContainer
 from nautilus_trader.backtest.engine import BacktestEngine

examples/live/binance_ema_cross.py

@@ -15,6 +15,10 @@
 # -------------------------------------------------------------------------------------------------
 
 from decimal import Decimal
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parents[2]))  # Allows relative imports from examples
 
 from examples.strategies.ema_cross_simple import EMACross
 from nautilus_trader.live.node import TradingNode
@@ -28,8 +32,13 @@
 # file. Here it is hardcoded into the example for clarity.
 config = {
     "trader": {
-        "name": "TESTER",              # Not sent beyond system boundary
-        "id_tag": "001",               # Used to ensure orders are unique for this trader
+        "name": "TESTER",  # Not sent beyond system boundary
+        "id_tag": "001",   # Used to ensure orders are unique for this trader
+    },
+
+    "system": {
+        "connection_timeout": 5.0,     # Timeout for successful connections for all engine clients
+        "disconnection_timeout": 5.0,  # Timeout for successful disconnection for all engine clients
         "check_residuals_delay": 5.0,  # How long to wait after stopping for residual events (secs)
     },
 

examples/live/binance_market_maker.py

@@ -15,6 +15,10 @@
 # -------------------------------------------------------------------------------------------------
 
 from decimal import Decimal
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parents[2]))  # Allows relative imports from examples
 
 from examples.strategies.volatility_market_maker import VolatilityMarketMaker
 from nautilus_trader.live.node import TradingNode
@@ -30,6 +34,11 @@
     "trader": {
         "name": "TESTER",              # Not sent beyond system boundary
         "id_tag": "001",               # Used to ensure orders are unique for this trader
+    },
+
+    "system": {
+        "connection_timeout": 5.0,     # Timeout for successful connections for all engine clients
+        "disconnection_timeout": 5.0,  # Timeout for successful disconnection for all engine clients
         "check_residuals_delay": 5.0,  # How long to wait after stopping for residual events (secs)
     },
 

examples/live/bitmex_ema_cross.py

@@ -15,6 +15,10 @@
 # -------------------------------------------------------------------------------------------------
 
 from decimal import Decimal
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parents[2]))  # Allows relative imports from examples
 
 from examples.strategies.ema_cross_simple import EMACross
 from nautilus_trader.live.node import TradingNode
@@ -30,6 +34,11 @@
     "trader": {
         "name": "TESTER",              # Not sent beyond system boundary
         "id_tag": "001",               # Used to ensure orders are unique for this trader
+    },
+
+    "system": {
+        "connection_timeout": 5.0,     # Timeout for successful connections for all engine clients
+        "disconnection_timeout": 5.0,  # Timeout for successful disconnection for all engine clients
         "check_residuals_delay": 5.0,  # How long to wait after stopping for residual events (secs)
     },