roboquant 0.2.3__tar.gz → 0.2.6__tar.gz

{roboquant-0.2.3/roboquant.egg-info → roboquant-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: roboquant
-Version: 0.2.3
+Version: 0.2.6
 Summary: A fast algo-trading platform
 Author-email: roboquant team <info@roboquant.org>
 Project-URL: Homepage, https://roboquant.org
@@ -32,6 +32,8 @@ Provides-Extra: yahoo
 Requires-Dist: yfinance~=0.2.36; extra == "yahoo"
 Provides-Extra: ibkr
 Requires-Dist: nautilus-ibapi~=10.19.2; extra == "ibkr"
+Provides-Extra: alpaca
+Requires-Dist: alpaca-py; extra == "alpaca"
 Provides-Extra: all
 Requires-Dist: roboquant[ibkr,torch,yahoo]; extra == "all"
 
@@ -50,7 +52,7 @@ Roboquant is an open-source algorithmic trading platform. It is flexible, user-f
 So whether you are a beginning retail trader or an established trading firm, roboquant can help you to develop robust and fully automated trading strategies. You can find out more at [roboquant.org](https://roboquant.org).
 
 ## Usage
-The following code snippet shows the steps to run a full back-test on a number of stocks.
+The following code snippet shows all the steps to run a full back-test on a number of stocks.
 
 ```python
 import roboquant as rq
@@ -69,6 +71,9 @@ Make sure you have Python version 3.10 or higher installed.
 python3 -m pip install --upgrade roboquant
 ```
 
+You can also try roboquant in an online Jupyter Notebook [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/neurallayer/roboquant-notebooks/HEAD?labpath=%2Fintro_roboquant.ipynb)
+
+
 The core of roboquant limits the number of dependencies. 
 But you can install roboquant including one or more of the optional dependencies if you require certain functionality:
 
@@ -113,8 +118,11 @@ python -m unittest discover -s tests/unit
 flake8 roboquant tests
 ```
 
-## Kotlin version
-Next to this Python version of `roboquant`, there is also a Kotlin version available.
-Both (will) share a similar API, just the used computer language is different.
+## License
+Roboquant is made available under the Apache 2.0 license. You can read more about the Apache 2.0 license on this page: https://www.apache.org/licenses/LICENSE-2.0.html
 
-Which one to use depends very much on personal preferences, skills and usage.
+## Disclaimer
+Absolutely no warranty is implied with this product. Use at your own risk. I provide no guarantee that it will be profitable, or that it won't lose all your money very quickly or doesn't contain bugs. All financial trading offers the possibility of loss. Leveraged trading, may result in you losing all your money, and still owing more. Backtested results are no guarantee of future performance. I can take no responsibility for any losses caused by live trading using roboquant. Use at your own risk. I am not registered or authorised by any financial regulator.
+
+## Kotlin version
+Next to this Python version of `roboquant`, there is also a Kotlin version available. Both (will) share a similar API, just the used computer language is different. Which one to use depends very much on personal preferences, skills and usage.

{roboquant-0.2.3 → roboquant-0.2.6}/README.md

@@ -13,7 +13,7 @@ Roboquant is an open-source algorithmic trading platform. It is flexible, user-f
 So whether you are a beginning retail trader or an established trading firm, roboquant can help you to develop robust and fully automated trading strategies. You can find out more at [roboquant.org](https://roboquant.org).
 
 ## Usage
-The following code snippet shows the steps to run a full back-test on a number of stocks.
+The following code snippet shows all the steps to run a full back-test on a number of stocks.
 
 ```python
 import roboquant as rq
@@ -32,6 +32,9 @@ Make sure you have Python version 3.10 or higher installed.
 python3 -m pip install --upgrade roboquant
 ```
 
+You can also try roboquant in an online Jupyter Notebook [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/neurallayer/roboquant-notebooks/HEAD?labpath=%2Fintro_roboquant.ipynb)
+
+
 The core of roboquant limits the number of dependencies. 
 But you can install roboquant including one or more of the optional dependencies if you require certain functionality:
 
@@ -76,8 +79,11 @@ python -m unittest discover -s tests/unit
 flake8 roboquant tests
 ```
 
-## Kotlin version
-Next to this Python version of `roboquant`, there is also a Kotlin version available.
-Both (will) share a similar API, just the used computer language is different.
+## License
+Roboquant is made available under the Apache 2.0 license. You can read more about the Apache 2.0 license on this page: https://www.apache.org/licenses/LICENSE-2.0.html
 
-Which one to use depends very much on personal preferences, skills and usage.
+## Disclaimer
+Absolutely no warranty is implied with this product. Use at your own risk. I provide no guarantee that it will be profitable, or that it won't lose all your money very quickly or doesn't contain bugs. All financial trading offers the possibility of loss. Leveraged trading, may result in you losing all your money, and still owing more. Backtested results are no guarantee of future performance. I can take no responsibility for any losses caused by live trading using roboquant. Use at your own risk. I am not registered or authorised by any financial regulator.
+
+## Kotlin version
+Next to this Python version of `roboquant`, there is also a Kotlin version available. Both (will) share a similar API, just the used computer language is different. Which one to use depends very much on personal preferences, skills and usage.

{roboquant-0.2.3 → roboquant-0.2.6}/pyproject.toml

@@ -1,9 +1,6 @@
 [tool.black]
 line-length = 127
 
-[tool.flake8]
-max-line-length = 127
-
 [tool.pytest.ini_options]
 minversion = "8.0"
 addopts = "-ra -q"
@@ -11,6 +8,9 @@ testpaths = [
     "tests/unit"
 ]
 
+[tool.pyright]
+reportOptionalOperand = "none"
+
 [tool.pylint.'MESSAGES CONTROL']
 max-line-length = 127
 disable = "too-few-public-methods,missing-module-docstring,missing-class-docstring,missing-function-docstring,unnecessary-ellipsis"
@@ -57,6 +57,7 @@ version = {attr = "roboquant.__version__"}
 torch = ["torch>=2.1.0", "tensorboard>=2.15.2"]
 yahoo = ["yfinance~=0.2.36"]
 ibkr = ["nautilus-ibapi~=10.19.2"]
+alpaca = ["alpaca-py"]
 all = [ "roboquant[torch,yahoo,ibkr]" ]
 
 

{roboquant-0.2.3 → roboquant-0.2.6}/roboquant/__init__.py

@@ -1,11 +1,11 @@
-__version__ = "0.2.3"
+__version__ = "0.2.6"
 
 from roboquant import brokers
 from roboquant import feeds
 from roboquant import journals
 from roboquant import strategies
 from roboquant import traders
-from .account import Account, OptionAccount, Position
+from .account import Account, Position, Converter, CurrencyConverter, OptionConverter
 from .config import Config
 from .event import Event, PriceItem, Candle, Trade, Quote
 from .order import Order, OrderStatus

roboquant-0.2.6/roboquant/account.py

@@ -0,0 +1,193 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+
+from roboquant.order import Order
+
+
+@dataclass(slots=True)
+class Position:
+    """Position of a symbol"""
+
+    size: Decimal
+    """Position size"""
+
+    avg_price: float
+    """Average price paid denoted in the currency of the symbol"""
+
+    mkt_price: float
+    """latest market price denoted in the currency of the symbol"""
+
+
+class Converter(ABC):
+    """Abstraction that enables trading symbols that are denoted in different currencies and/or contact sizes"""
+
+    @abstractmethod
+    def __call__(self, symbol: str, time: datetime) -> float:
+        """Return the conversion rate for the symbol at the given time"""
+        ...
+
+
+class OptionConverter(Converter):
+    """
+    This converter handles common option contracts of size 100 and 10 and serves as an example.
+
+    If no contract size is registered for a symbol, it calculates one based on the symbol name.
+    If the symbol is not recognized as an OCC compliant option symbol, it is assumed to have a
+    contract size of 1.0
+    """
+
+    def __init__(self):
+        super().__init__()
+        self._contract_sizes: dict[str, float] = {}
+
+    def register(self, symbol: str, contract_size: float = 100.0):
+        """Register a contract-size for a symbol"""
+        self._contract_sizes[symbol] = contract_size
+
+    def __call__(self, symbol: str, time: datetime) -> float:
+        contract_size = self._contract_sizes.get(symbol)
+
+        # If no contract has been registered, we try to defer the contract size from the symbol
+        if contract_size is None:
+            if len(symbol) == 21:
+                # OCC compliant option symbol
+                symbol = symbol[0:6].rstrip()
+                contract_size = 10.0 if symbol[-1] == "7" else 100.0
+            else:
+                # not an option symbol
+                contract_size = 1.0
+
+            self._contract_sizes[symbol] = contract_size
+
+        return contract_size
+
+
+class CurrencyConverter(Converter):
+    """Supports trading in symbols that are denoted in a different currency from the base currency of the account"""
+
+    def __init__(self, base_currency="USD", default_symbol_currency: str | None = "USD"):
+        super().__init__()
+        self.rates = {}
+        self.base_currency = base_currency
+        self.default_symbol_currency = default_symbol_currency
+        self.registered_symbols: dict[str, str] = {}
+
+    def register_symbol(self, symbol: str, currency: str):
+        """Register a symbol and its denoted currency"""
+        self.registered_symbols[symbol] = currency
+
+    def register_rate(self, currency: str, rate: float):
+        """Register a conversion rate from a currency to the base_currency"""
+        self.rates[currency] = rate
+
+    def __call__(self, symbol: str, _: datetime) -> float:
+        currency = self.registered_symbols.get(symbol, self.default_symbol_currency)
+        if not currency:
+            raise ValueError(f"no currency or default_symbol_currency registered for symbol={symbol}")
+        if currency == self.base_currency:
+            return 1.0
+        return self.rates[currency]
+
+
+class Account:
+    """Represents a trading account with all monetary amounts denoted in a single currency.
+    The account maintains the following state during a run:
+
+    - Available buying power for orders in the base currency of the account
+    - Cash available
+    - The open positions
+    - Orders
+    - Calculated derived equity value of the account in the base currency of the account
+    - The last time the account was updated
+
+    Only the broker updates the account and does this only during its `sync` method.
+    """
+
+    __converter: Converter | None = None
+
+    def __init__(self):
+        self.buying_power: float = 0.0
+        self.positions: dict[str, Position] = {}
+        self.orders: list[Order] = []
+        self.last_update: datetime = datetime.fromisoformat("1900-01-01T00:00:00+00:00")
+        self.cash: float = 0.0
+
+    @staticmethod
+    def register_converter(converter: Converter):
+        """Register a converter"""
+        Account.__converter = converter
+
+    def contract_value(self, symbol: str, size: Decimal, price: float) -> float:
+        # pylint: disable=not-callable
+        """Return the total value of the provided contract size denoted in the base currency of the account."""
+        rate = 1.0 if not Account.__converter else Account.__converter(symbol, self.last_update)
+        return float(size) * price * rate
+
+    def mkt_value(self) -> float:
+        """Return the sum of the market values of the open positions in the account.
+
+        The returned value is denoted in the base currency of the account.
+        """
+        return sum(
+            [self.contract_value(symbol, pos.size, pos.mkt_price) for symbol, pos in self.positions.items()],
+            0.0,
+        )
+
+    def equity(self) -> float:
+        """Return the equity of the account. It calcaluates the sum of the mkt value of
+        each open position and adds the available cash.
+
+        The returned value is denoted in the base currency of the account.
+        """
+        return self.cash + self.mkt_value()
+
+    def unrealized_pnl(self) -> float:
+        """Return the sum of the unrealized profit and loss for the open position.
+
+        The returned value is denoted in the base currency of the account.
+        """
+        return sum(
+            [self.contract_value(symbol, pos.size, pos.mkt_price - pos.avg_price) for symbol, pos in self.positions.items()],
+            0.0,
+        )
+
+    def has_open_order(self, symbol: str) -> bool:
+        """Return True if there is at least one open order for the symbol, False otherwise"""
+
+        for order in self.orders:
+            if order.symbol == symbol and order.is_open:
+                return True
+        return False
+
+    def get_open_orders(self, symbol: str) -> list[Order]:
+        """Return a list of open orders for the provided symbol"""
+        return [order for order in self.orders if order.is_open and order.symbol == symbol]
+
+    def get_position_size(self, symbol: str) -> Decimal:
+        """Return the position size for a symbol"""
+        pos = self.positions.get(symbol)
+        return pos.size if pos else Decimal(0)
+
+    def open_orders(self):
+        """Return a list with the open orders"""
+        return [order for order in self.orders if order.is_open]
+
+    def __repr__(self) -> str:
+        p = [f"{v.size}@{k}" for k, v in self.positions.items()]
+        p_str = ", ".join(p) or "none"
+
+        o = [f"{o.size}@{o.symbol}" for o in self.open_orders()]
+        o_str = ", ".join(o) or "none"
+
+        result = (
+            f"""buying power : {self.buying_power:_.2f}\n"""
+            f"""cash         : {self.cash:_.2f}\n"""
+            f"""equity       : {self.equity():_.2f}\n"""
+            f"""positions    : {p_str}\n"""
+            f"""mkt value    : {self.mkt_value():_.2f}\n"""
+            f"""open orders  : {o_str}\n"""
+            f"""last update  : {self.last_update}"""
+        )
+        return result

{roboquant-0.2.3 → roboquant-0.2.6}/roboquant/brokers/broker.py

@@ -34,3 +34,15 @@ class Broker(Protocol):
 
         """
         ...
+
+
+def _update_positions(account: Account, event: Event | None, price_type: str = "DEFAULT"):
+    """update the open positions in the account with the latest market prices"""
+    if not event:
+        return
+
+    account.last_update = event.time
+
+    for symbol, position in account.positions.items():
+        if price := event.get_price(symbol, price_type):
+            position.mkt_price = price

roboquant-0.2.3/roboquant/brokers/ibkrbroker.py → roboquant-0.2.6/roboquant/brokers/ibkr.py

@@ -14,7 +14,7 @@ from ibapi.wrapper import EWrapper
 from roboquant.account import Account, Position
 from roboquant.event import Event
 from roboquant.order import Order, OrderStatus
-from .broker import Broker
+from .broker import Broker, _update_positions
 
 assert VERSION["major"] == 10 and VERSION["minor"] == 19, "Wrong version of the IBAPI found"
 
@@ -28,7 +28,7 @@ class _IBApi(EWrapper, EClient):
         EClient.__init__(self, self)
         self.orders: dict[str, Order] = {}
         self.positions: dict[str, Position] = {}
-        self.account = {"EquityWithLoanValue": 0.0, "AvailableFunds": 0.0}
+        self.__account = {AccountSummaryTags.TotalCashValue: 0.0, AccountSummaryTags.BuyingPower: 0.0}
         self.__account_end = threading.Condition()
         self.__order_id = 0
 
@@ -44,11 +44,13 @@ class _IBApi(EWrapper, EClient):
     def position(self, account: str, contract: Contract, position: Decimal, avgCost: float):
         logger.debug("position=%s symbol=%s  avgCost=%s", position, contract.localSymbol, avgCost)
         symbol = contract.localSymbol or contract.symbol
-        self.positions[symbol] = Position(position, avgCost)
+        old_position = self.positions.get(symbol)
+        mkt_price = old_position.mkt_price if old_position else avgCost
+        self.positions[symbol] = Position(position, avgCost, mkt_price)
 
     def accountSummary(self, reqId: int, account: str, tag: str, value: str, currency: str):
         logger.debug("account %s=%s", tag, value)
-        self.account[tag] = float(value)
+        self.__account[tag] = float(value)
 
     def accountSummaryEnd(self, reqId: int):
         with self.__account_end:
@@ -71,32 +73,32 @@ class _IBApi(EWrapper, EClient):
     def request_account(self):
         """blocking call till account summary has been received"""
         buyingpower_tag = AccountSummaryTags.BuyingPower
-        equity_tag = AccountSummaryTags.NetLiquidation
+        cash_tag = AccountSummaryTags.TotalCashValue
         with self.__account_end:
-            super().reqAccountSummary(1, "All", f"{buyingpower_tag},{equity_tag}")
+            super().reqAccountSummary(1, "All", f"{buyingpower_tag},{cash_tag}")
             self.__account_end.wait()
 
     def get_buying_power(self):
         buyingpower_tag = AccountSummaryTags.BuyingPower
-        return self.account[buyingpower_tag] or 0.0
+        return self.__account[buyingpower_tag] or 0.0
 
-    def get_equity(self):
-        equity_tag = AccountSummaryTags.NetLiquidation
-        return self.account[equity_tag] or 0.0
+    def get_cash(self):
+        cash_tag = AccountSummaryTags.TotalCashValue
+        return self.__account[cash_tag] or 0.0
 
     def orderStatus(
-            self,
-            orderId,
-            status,
-            filled,
-            remaining,
-            avgFillPrice,
-            permId,
-            parentId,
-            lastFillPrice,
-            clientId,
-            whyHeld,
-            mktCapPrice,
+        self,
+        orderId,
+        status,
+        filled,
+        remaining,
+        avgFillPrice,
+        permId,
+        parentId,
+        lastFillPrice,
+        clientId,
+        whyHeld,
+        mktCapPrice,
     ):
         logger.debug("order status orderId=%s status=%s fill=%s", orderId, status, filled)
         orderId = str(orderId)
@@ -122,31 +124,51 @@ class IBKRBroker(Broker):
         Map symbols to IBKR contracts.
         If a symbol is not found, the symbol is assumed to represent a US stock
 
+    host
+        the ip number of the host where TWS or IB Gateway is running.
+
+    port
+       By default, TWS uses socket port 7496 for live sessions and 7497 for paper sessions.
+       IB Gateway by contrast uses 4001 for live sessions and 4002 for paper sessions.
+       However these are just defaults, and can be modified as desired.
+
+    client_id
+        The client id to use to connect to TWS or IB Gateway.
     """
 
-    def __init__(self, host="127.0.0.1", port=4002, account=None, client_id=123) -> None:
-        self.__account = account or Account()
+    def __init__(self, host="127.0.0.1", port=4002, client_id=123) -> None:
+        self.__account = Account()
         self.contract_mapping: dict[str, Contract] = {}
         api = _IBApi()
         api.connect(host, port, client_id)
         self.__api = api
         self.__has_new_orders_since_sync = False
+        self.price_type = "DEFAULT"
 
         # Start the handling in a thread
         self.__api_thread = threading.Thread(target=api.run, daemon=True)
         self.__api_thread.start()
         time.sleep(3.0)
 
+    @classmethod
+    def use_tws(cls, client_id=123):
+        """Return a broker connected to the TWS papertrade instance with its default port (7497) settings"""
+        return cls("127.0.0.1", 7497, client_id)
+
+    @classmethod
+    def use_ibgateway(cls, client_id=123):
+        """Return a broker connected to a IB Gateway papertrade instance with its default port (4002) settings"""
+        return cls("127.0.0.1", 4002, client_id)
+
     def disconnect(self):
-        self.__api.reader.conn.disconnect()
+        self.__api.reader.conn.disconnect()  # type: ignore
 
     def _should_sync(self, now: datetime):
         """Avoid too many API calls"""
         return self.__has_new_orders_since_sync or now - self.__account.last_update > timedelta(seconds=1)
 
     def sync(self, event: Event | None = None) -> Account:
-        """Sync with the IBKR account
-        """
+        """Sync with the IBKR account"""
 
         logger.debug("start sync")
         now = datetime.now(timezone.utc)
@@ -155,7 +177,7 @@ class IBKRBroker(Broker):
             # Let make sure we don't use IBKRBroker by mistake during a back-test.
             if now - event.time > timedelta(minutes=30):
                 logger.critical("received event from the past, now=%s event-time=%s", now, event.time)
-                raise ValueError(f"received event to far in the past now={now} event-time={event.time}")
+                raise ValueError(f"received event too far in the past now={now} event-time={event.time}")
 
         api = self.__api
         acc = self.__account
@@ -170,8 +192,9 @@ class IBKRBroker(Broker):
             acc.positions = {k: v for k, v in api.positions.items() if not v.size.is_zero()}
             acc.orders = list(api.orders.values())
             acc.buying_power = api.get_buying_power()
-            acc.equity = api.get_equity()
+            acc.cash = api.get_cash()
 
+        _update_positions(acc, event)
         logger.debug("end sync")
         return acc
 
@@ -184,41 +207,64 @@ class IBKRBroker(Broker):
                 # avoid to many API calls
                 time.sleep(1)
 
-            assert not order.closed, "cannot place a closed order"
+            assert order.is_open, "can only place open orders"
             if order.size.is_zero():
-                assert order.id is not None
+                assert order.id is not None, "can only cancel orders with an id"
                 self.__api.cancelOrder(int(order.id), "")
             else:
                 if order.id is None:
                     order.id = self.__api.get_next_order_id()
                     self.__api.orders[order.id] = order
-                ibkr_order = self.__get_order(order)
-                contract = self.contract_mapping.get(order.symbol) or self._get_default_contract(order.symbol)
+                ibkr_order = self._get_order(order)
+                contract = self._get_contract(order)
                 self.__api.placeOrder(int(order.id), contract, ibkr_order)
 
-    def _get_default_contract(self, symbol: str) -> Contract:
-        """If no contract can be found in the `contract_mapping` dict, this method is called to get a default IBKR contract
-        for the provided symbol.
+    @staticmethod
+    def __update_ibkr_object(obj, update):
+        if not update:
+            return
+        assert isinstance(update, dict)
+        for name, value in update.items():
+            if hasattr(obj, name):
+                setattr(obj, name, value)
+            else:
+                logger.warning("unknown field name=%s value=%s", name, value)
+
+    def _get_contract(self, order: Order) -> Contract:
+        """Map an order to a IBKR contract."""
 
-        The default implementation assumes it is a US stock symbol with SMART exchange routing.
-        """
+        c = self.contract_mapping.get(order.symbol)
+
+        if not c:
+            c = Contract()
+            c.symbol = order.symbol
+            c.secType = "STK"
+            c.currency = "USD"
+            c.exchange = "SMART"  # use smart routing by default
+
+        # Override attributes
+        IBKRBroker.__update_ibkr_object(c, order.info.get("contract"))
 
-        c = Contract()
-        c.symbol = symbol
-        c.secType = "STK"
-        c.currency = "USD"
-        c.exchange = "SMART"  # use smart routing by default
         return c
 
-    @staticmethod
-    def __get_order(order: Order):
+    def _get_order(self, order: Order) -> IBKROrder:
+        """Map an order to a IBKR order."""
         o = IBKROrder()
         o.action = "BUY" if order.is_buy else "SELL"
         o.totalQuantity = abs(order.size)
-        o.tif = "GTC"
+        if order.gtd:
+            o.tif = "GTD"
+            o.goodTillDate = order.gtd.strftime("%Y%m%d %H:%M:%S %Z")
+        else:
+            o.tif = "GTC"
+
         if order.limit:
             o.orderType = "LMT"
             o.lmtPrice = order.limit
         else:
             o.orderType = "MKT"
+
+        # Override attributes
+        IBKRBroker.__update_ibkr_object(o, order.info.get("order"))
+
         return o