bbstrader 2.0.3__cp312-cp312-macosx_11_0_arm64.whl

bbstrader/btengine/event.py

@@ -0,0 +1,229 @@
+from datetime import datetime
+from enum import Enum
+from typing import Literal, Optional, Union
+
+__all__ = ["Event", "Events", "MarketEvent", "SignalEvent", "OrderEvent", "FillEvent"]
+
+
+class Event:
+    """
+    Event is base class providing an interface for all subsequent
+    (inherited) events, that will trigger further events in the
+    trading infrastructure.
+    Since in many implementations the Event objects will likely develop greater
+    complexity, it is thus being "future-proofed" by creating a class hierarchy.
+    The Event class is simply a way to ensure that all events have a common interface
+    and can be handled in a consistent manner.
+    """
+
+    ...
+
+
+class Events(Enum):
+    MARKET = "MARKET"
+    SIGNAL = "SIGNAL"
+    ORDER = "ORDER"
+    FILL = "FILL"
+
+
+class MarketEvent(Event):
+    """
+    Market Events are triggered when the outer while loop of the backtesting
+    system begins a new `"heartbeat"`. It occurs when the `DataHandler` object
+    receives a new update of market data for any symbols which are currently
+    being tracked. It is used to `trigger the Strategy object` generating
+    new `trading signals`. The event object simply contains an identification
+    that it is a market event, with no other structure.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialises the MarketEvent.
+        """
+        self.type = Events.MARKET
+
+
+class SignalEvent(Event):
+    """
+    The `Strategy object` utilises market data to create new `SignalEvents`.
+    The SignalEvent contains a `strategy ID`, a `ticker symbol`, a `timestamp`
+    for when it was generated, a `direction` (long or short) and a `"strength"`
+    indicator (this is useful for mean reversion strategies) and the `quantiy`
+    to buy or sell. The `SignalEvents` are utilised by the `Portfolio object`
+    as advice for how to trade.
+    """
+
+    def __init__(
+        self,
+        strategy_id: int,
+        symbol: str,
+        datetime: datetime,
+        signal_type: Literal["LONG", "SHORT", "EXIT"],
+        quantity: Union[int, float] = 100,
+        strength: Union[int, float] = 1.0,
+        price: Optional[Union[int, float]] = None,
+        stoplimit: Optional[Union[int, float]] = None,
+    ) -> None:
+        """
+        Initialises the SignalEvent.
+
+        Args:
+            strategy_id (int): The unique identifier for the strategy that
+                generated the signal.
+
+            symbol (str): The ticker symbol, e.g. 'GOOG'.
+            datetime (datetime): The timestamp at which the signal was generated.
+            signal_type (str): 'LONG' or 'SHORT' or 'EXIT'.
+            quantity (int | float): An optional integer (or float) representing the order size.
+            strength (int | float): An adjustment factor "suggestion" used to scale
+                quantity at the portfolio level. Useful for pairs strategies.
+            price (int | float): An optional price to be used when the signal is generated.
+            stoplimit (int | float): An optional stop-limit price for the signal
+        """
+        self.type = Events.SIGNAL
+        self.strategy_id = strategy_id
+        self.symbol = symbol
+        self.datetime = datetime
+        self.signal_type = signal_type
+        self.quantity = quantity
+        self.strength = strength
+        self.price = price
+        self.stoplimit = stoplimit
+
+
+class OrderEvent(Event):
+    """
+    When a Portfolio object receives `SignalEvents` it assesses them
+    in the wider context of the portfolio, in terms of risk and position sizing.
+    This ultimately leads to `OrderEvents` that will be sent to an `ExecutionHandler`.
+
+    The `OrderEvents` is slightly more complex than a `SignalEvents` since
+    it contains a quantity field in addition to the aforementioned properties
+    of SignalEvent. The quantity is determined by the Portfolio constraints.
+    In addition the OrderEvent has a `print_order()` method, used to output the
+    information to the console if necessary.
+    """
+
+    def __init__(
+        self,
+        symbol: str,
+        order_type: Literal["MKT", "LMT", "STP", "STPLMT"],
+        quantity: Union[int, float],
+        direction: Literal["BUY", "SELL"],
+        price: Optional[Union[int, float]] = None,
+        signal: Optional[str] = None,
+    ) -> None:
+        """
+        Initialises the order type, setting whether it is
+        a Market order ('MKT') or Limit order ('LMT'), or Stop order ('STP').
+        a quantity (integral or float) and its direction ('BUY' or 'SELL').
+
+        Args:
+            symbol (str): The instrument to trade.
+            order_type (str): 'MKT' or 'LMT' for Market or Limit.
+            quantity (int | float): Non-negative number for quantity.
+            direction (str): 'BUY' or 'SELL' for long or short.
+            price (int | float): The price at which to order.
+            signal (str): The signal that generated the order.
+        """
+        self.type = Events.ORDER
+        self.symbol = symbol
+        self.order_type = order_type
+        self.quantity = quantity
+        self.direction = direction
+        self.price = price
+        self.signal = signal
+
+    def print_order(self) -> None:
+        """
+        Outputs the values within the Order.
+        """
+        print(
+            "Order: Symbol=%s, Type=%s, Quantity=%s, Direction=%s, Price=%s"
+            % (
+                self.symbol,
+                self.order_type,
+                self.quantity,
+                self.direction,
+                self.price,
+            )
+        )
+
+
+class FillEvent(Event):
+    """
+    When an `ExecutionHandler` receives an `OrderEvent` it must transact the order.
+    Once an order has been transacted it generates a `FillEvent`, which describes
+    the cost of purchase or sale as well as the transaction costs, such as fees
+    or slippage.
+
+    The `FillEvent` is the Event with the greatest complexity.
+    It contains a `timestamp` for when an order was filled, the `symbol`
+    of the order and the `exchange` it was executed on, the `quantity`
+    of shares transacted, the `actual price of the purchase` and the `commission
+    incurred`.
+
+    The commission is calculated using the Interactive Brokers commissions.
+    For US API orders this commission is `1.30 USD` minimum per order, with a flat
+    rate of either 0.013 USD or 0.08 USD per share depending upon whether
+    the trade size is below or above `500 units` of stock.
+    """
+
+    def __init__(
+        self,
+        timeindex: datetime,
+        symbol: str,
+        exchange: str,
+        quantity: Union[int, float],
+        direction: Literal["BUY", "SELL"],
+        fill_cost: Optional[Union[int, float]],
+        commission: Optional[float] = None,
+        order: Optional[str] = None,
+    ) -> None:
+        """
+        Initialises the FillEvent object. Sets the symbol, exchange,
+        quantity, direction, cost of fill and an optional
+        commission.
+
+        If commission is not provided, the Fill object will
+        calculate it based on the trade size and Interactive
+        Brokers fees.
+
+        Args:
+            timeindex (datetime): The bar-resolution when the order was filled.
+            symbol (str): The instrument which was filled.
+            exchange (str): The exchange where the order was filled.
+            quantity (int | float): The filled quantity.
+            direction (str): The direction of fill `('LONG', 'SHORT', 'EXIT')`
+            fill_cost (int | float): Price of the shares when filled.
+            commission (float | None): An optional commission sent from IB.
+            order (str): The order that this fill is related
+        """
+        self.type = Events.FILL
+        self.timeindex = timeindex
+        self.symbol = symbol
+        self.exchange = exchange
+        self.quantity = quantity
+        self.direction = direction
+        self.fill_cost = fill_cost
+        # Calculate commission
+        if commission is None:
+            self.commission: float = self.calculate_ib_commission()
+        else:
+            self.commission = commission
+        self.order = order
+
+    def calculate_ib_commission(self) -> float:
+        """
+        Calculates the fees of trading based on an Interactive
+        Brokers fee structure for API, in USD.
+        This does not include exchange or ECN fees.
+        Based on "US API Directed Orders":
+        https://www.interactivebrokers.com/en/index.php?f=commission&p=stocks2
+        """
+        full_cost = 1.3
+        if self.quantity <= 500:
+            full_cost = max(1.3, 0.013 * self.quantity)
+        else:
+            full_cost = max(1.3, 0.008 * self.quantity)
+        return full_cost

bbstrader/btengine/execution.py

@@ -0,0 +1,287 @@
+from abc import ABCMeta, abstractmethod
+from queue import Queue
+from typing import Any, Union
+
+from loguru import logger
+
+from bbstrader.btengine.data import DataHandler
+from bbstrader.btengine.event import Events, FillEvent, OrderEvent
+from bbstrader.config import BBSTRADER_DIR
+from bbstrader.metatrader.account import Account
+from bbstrader.metatrader.utils import SymbolType
+
+__all__ = ["ExecutionHandler", "SimExecutionHandler", "MT5ExecutionHandler"]
+
+
+logger.add(
+    f"{BBSTRADER_DIR}/logs/execution.log",
+    enqueue=True,
+    level="INFO",
+    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {name} | {message}",
+)
+
+
+class ExecutionHandler(metaclass=ABCMeta):
+    """
+    The ExecutionHandler abstract class handles the interaction
+    between a set of order objects generated by a Portfolio and
+    the ultimate set of Fill objects that actually occur in the
+    market.
+
+    The handlers can be used to subclass simulated brokerages
+    or live brokerages, with identical interfaces. This allows
+    strategies to be backtested in a very similar manner to the
+    live trading engine.
+
+    The ExecutionHandler described here is exceedingly simple,
+    since it fills all orders at the current market price.
+    This is highly unrealistic, for other markets thant ``CFDs``
+    but serves as a good baseline for improvement.
+    """
+
+    @abstractmethod
+    def execute_order(self, event: OrderEvent) -> None:
+        """
+        Takes an Order event and executes it, producing
+        a Fill event that gets placed onto the Events queue.
+
+        Args:
+            event (OrderEvent): Contains an Event object with order information.
+        """
+        raise NotImplementedError("Should implement execute_order()")
+
+
+class SimExecutionHandler(ExecutionHandler):
+    """
+    The simulated execution handler simply converts all order
+    objects into their equivalent fill objects automatically
+    without latency, slippage or fill-ratio issues.
+
+    This allows a straightforward "first go" test of any strategy,
+    before implementation with a more sophisticated execution
+    handler.
+    """
+
+    def __init__(
+        self,
+        events: "Queue[Union[FillEvent, OrderEvent]]",
+        data: DataHandler,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialises the handler, setting the event queues
+        up internally.
+
+        Args:
+            events (Queue): The Queue of Event objects.
+        """
+        self.events = events
+        self.bardata = data
+        self.logger = kwargs.get("logger") or logger
+        self.commissions = kwargs.get("commission")
+        self.exchange = kwargs.get("exchange", "ARCA")
+
+    def execute_order(self, event: OrderEvent) -> None:
+        """
+        Simply converts Order objects into Fill objects naively,
+        i.e. without any latency, slippage or fill ratio problems.
+
+        Args:
+            event (OrderEvent): Contains an Event object with order information.
+        """
+        if event.type == Events.ORDER:
+            dtime = self.bardata.get_latest_bar_datetime(event.symbol)
+            fill_event = FillEvent(
+                timeindex=dtime,  # type: ignore
+                symbol=event.symbol,
+                exchange=self.exchange,
+                quantity=event.quantity,
+                direction=event.direction,
+                fill_cost=None,
+                commission=self.commissions,
+                order=event.signal,
+            )
+            self.events.put(fill_event)
+            price = event.price or 0.0
+            self.logger.info(
+                f"{event.direction} ORDER FILLED: SYMBOL={event.symbol}, "
+                f"QUANTITY={event.quantity}, PRICE @{round(price, 5)} EXCHANGE={fill_event.exchange}",
+                custom_time=fill_event.timeindex,
+            )
+
+
+class MT5ExecutionHandler(ExecutionHandler):
+    """
+    The main role of `MT5ExecutionHandler` class is to estimate the execution fees
+    for different asset classes on the MT5 terminal.
+
+    Generally we have four types of fees when we execute trades using the MT5 terminal
+    (commissions, swap, spread and other fees). But most of these fees depend on the specifications
+    of each instrument and the duration of the transaction for the swap for example.
+
+    Calculating the exact fees for each instrument would be a bit complex because our Backtest engine
+    and the Portfolio class do not take into account the duration of each trade to apply the appropriate
+    rate for the swap for example. So we have to use only the model of calculating the commissions
+    for each asset class and each instrument.
+
+    The second thing that must be taken into account on MT5 is the type of account offered by the broker.
+    Brokers have different account categories each with its specifications for each asset class and each instrument.
+    Again considering all these conditions would make our class very complex. So we took the `Raw Spread`
+    account fee calculation model from [Just Market](https://one.justmarkets.link/a/tufvj0xugm/registration/trader)
+    for indicies, forex, commodities and crypto. We used the [Admiral Market](https://cabinet.a-partnership.com/visit/?bta=35537&brand=admiralmarkets)
+    account fee calculation model from `Trade.MT5` account type for stocks and ETFs.
+
+    NOTE:
+        This class only works with `bbstrader.metatrader.data.MT5DataHandler` class.
+    """
+
+    def __init__(
+        self,
+        events: "Queue[Union[FillEvent, OrderEvent]]",
+        data: DataHandler,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialises the handler, setting the event queues up internally.
+
+        Args:
+            events (Queue): The Queue of Event objects.
+        """
+        self.events = events
+        self.bardata = data
+        self.logger = kwargs.get("logger") or logger
+        self.commissions = kwargs.get("commission")
+        self.exchange = kwargs.get("exchange", "MT5")
+        self.__account = Account(**kwargs)
+
+    def _calculate_lot(
+        self, symbol: str, quantity: Union[int, float], price: Union[int, float]
+    ) -> float:
+        symbol_type = self.__account.get_symbol_type(symbol)
+        symbol_info = self.__account.get_symbol_info(symbol)
+        contract_size = symbol_info.trade_contract_size
+
+        lot = (quantity * price) / (contract_size * price)
+        if contract_size == 1:
+            lot = float(quantity)
+        if (
+            symbol_type
+            in (SymbolType.COMMODITIES, SymbolType.FUTURES, SymbolType.CRYPTO)
+            and contract_size > 1
+        ):
+            lot = quantity / contract_size
+        if symbol_type == SymbolType.FOREX:
+            lot = float(quantity * price / contract_size)
+        return self.__account.broker.validate_lot_size(symbol, lot)
+
+    
+    def _estimate_total_fees(
+        self,
+        symbol: str,
+        lot: float,
+        qty: Union[int, float],
+        price: Union[int, float],
+    ) -> float:
+        symbol_type = self.__account.get_symbol_type(symbol)
+        if symbol_type in (SymbolType.STOCKS, SymbolType.ETFs):
+            return self._estimate_stock_commission(symbol, qty, price)
+        elif symbol_type == SymbolType.FOREX:
+            return self._estimate_forex_commission(lot)
+        elif symbol_type == SymbolType.COMMODITIES:
+            return self._estimate_commodity_commission(lot)
+        elif symbol_type == SymbolType.INDICES:
+            return self._estimate_index_commission(lot)
+        elif symbol_type == SymbolType.FUTURES:
+            return self._estimate_futures_commission()
+        elif symbol_type == SymbolType.CRYPTO:
+            return self._estimate_crypto_commission()
+        else:
+            return 0.0
+
+    def _estimate_stock_commission(
+        self, symbol: str, qty: Union[int, float], price: Union[int, float]
+    ) -> float:
+        # https://admiralmarkets.com/start-trading/contract-specifications?regulator=jsc
+        min_com = 1.0
+        min_aud = 8.0
+        min_dkk = 30.0
+        min_nok = min_sek = 10.0
+        us_com = 0.02  # per chare
+        ger_fr_uk_cm = 0.001  # percent
+        eu_asia_cm = 0.0015  # percent
+        if (
+            symbol in self.__account.get_stocks_from_country("USA")
+            or self.__account.get_symbol_type(symbol) == SymbolType.ETFs
+            and self.__account.get_currency_rates(symbol)["mc"] == "USD"
+        ):
+            return max(min_com, qty * us_com)
+        elif (
+            symbol in self.__account.get_stocks_from_country("GBR")
+            or symbol in self.__account.get_stocks_from_country("FRA")
+            or symbol in self.__account.get_stocks_from_country("DEU")
+            or self.__account.get_symbol_type(symbol) == SymbolType.ETFs
+            and self.__account.get_currency_rates(symbol)["mc"] in ["GBP", "EUR"]
+        ):
+            return max(min_com, qty * price * ger_fr_uk_cm)
+        else:
+            if self.__account.get_currency_rates(symbol)["mc"] == "AUD":
+                return max(min_aud, qty * price * eu_asia_cm)
+            elif self.__account.get_currency_rates(symbol)["mc"] == "DKK":
+                return max(min_dkk, qty * price * eu_asia_cm)
+            elif self.__account.get_currency_rates(symbol)["mc"] == "NOK":
+                return max(min_nok, qty * price * eu_asia_cm)
+            elif self.__account.get_currency_rates(symbol)["mc"] == "SEK":
+                return max(min_sek, qty * price * eu_asia_cm)
+            else:
+                return max(min_com, qty * price * eu_asia_cm)
+
+    def _estimate_forex_commission(self, lot: float) -> float:
+        return 3.0 * lot
+
+    def _estimate_commodity_commission(self, lot: float) -> float:
+        return 3.0 * lot
+
+    def _estimate_index_commission(self, lot: float) -> float:
+        return 0.25 * lot
+
+    def _estimate_futures_commission(self) -> float:
+        return 0.0
+
+    def _estimate_crypto_commission(self) -> float:
+        return 0.0
+
+    def execute_order(self, event: OrderEvent) -> None:
+        """
+        Executes an Order event by converting it into a Fill event.
+
+        Args:
+            event (OrderEvent): Contains an Event object with order information.
+        """
+        if event.type == Events.ORDER:
+            symbol = event.symbol
+            direction = event.direction
+            quantity = event.quantity
+            price = event.price
+            if price is None:
+                price = self.bardata.get_latest_bar_value(symbol, "close")
+            lot = self._calculate_lot(symbol, quantity, price)
+            fees = self._estimate_total_fees(symbol, lot, quantity, price)
+            dtime = self.bardata.get_latest_bar_datetime(symbol)
+            commission = self.commissions or fees
+            fill_event = FillEvent(
+                timeindex=dtime,  # type: ignore
+                symbol=symbol,
+                exchange=self.exchange,
+                quantity=quantity,
+                direction=direction,
+                fill_cost=None,
+                commission=commission,
+                order=event.signal,
+            )
+            self.events.put(fill_event)
+            log_price = event.price or 0.0
+            self.logger.info(
+                f"{direction} ORDER FILLED: SYMBOL={symbol}, QUANTITY={quantity}, "
+                f"PRICE @{round(log_price, 5)} EXCHANGE={fill_event.exchange}",
+                custom_time=fill_event.timeindex,
+            )