bbstrader 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

bbstrader/btengine/data.py

@@ -8,6 +8,7 @@ from queue import Queue
 from abc import ABCMeta, abstractmethod
 from bbstrader.metatrader.rates import Rates
 from bbstrader.btengine.event import MarketEvent
+from datetime import datetime
 
 
 __all__ = [
@@ -260,7 +261,7 @@ class HistoricCSVDataHandler(BaseCSVDataHandler):
         csv_dir = kwargs.get("csv_dir")
         super().__init__(events, symbol_list, csv_dir)
 
-MAX_BARS = 10_000_000
+
 class MT5HistoricDataHandler(BaseCSVDataHandler):
     """
     Downloads historical data from MetaTrader 5 (MT5) and provides 
@@ -281,19 +282,16 @@ class MT5HistoricDataHandler(BaseCSVDataHandler):
             symbol_list (List[str]): A list of symbol strings to download data for.
             **kwargs: Keyword arguments for data retrieval:
                 time_frame (str): MT5 time frame (e.g., 'D1' for daily).
-                max_bars (int): Maximum number of bars to download per symbol.
-                start_pos (int | str, optional): Starting bar position (default: 0).
-                    If it set to `str`, it must be in 'YYYY-MM-DD' format and
-                session_duration (int | float): Number of trading hours per day.
+                mt5_start (datetime): Start date for historical data.
+                mt5_end (datetime): End date for historical data.
                 mt5_data (str): Directory for storing data (default: 'mt5_data').
 
         Note:
             Requires a working connection to an MT5 terminal.
         """
         self.tf = kwargs.get('time_frame', 'D1')
-        self.start_pos = kwargs.get('start_pos', 0)
-        self.max_bars = kwargs.get('max_bars', MAX_BARS)
-        self.sd = kwargs.get('session_duration', 6.5)
+        self.start = kwargs.get('mt5_start')
+        self.end = kwargs.get('mt5_end', datetime.now())
         self.data_dir = kwargs.get('mt5_data', 'mt5_data')
         self.symbol_list = symbol_list
         csv_dir = self._download_data(self.data_dir)
@@ -304,8 +302,10 @@ class MT5HistoricDataHandler(BaseCSVDataHandler):
         data_dir.mkdir(parents=True, exist_ok=True)
         for symbol in self.symbol_list:
             try:
-                rate = Rates(symbol, self.tf, self.start_pos, self.max_bars, self.sd)
-                data = rate.get_rates_from_pos()
+                rate = Rates(symbol=symbol, time_frame=self.tf)
+                data = rate.get_historical_data(
+                    date_from=self.start, date_to=self.end
+                )
                 if data is None:
                     raise ValueError(f"No data found for {symbol}")
                 data.to_csv(data_dir / f'{symbol}.csv')
@@ -359,16 +359,29 @@ class YFHistoricDataHandler(BaseCSVDataHandler):
         return cache_dir
 
 
-# TODO # Get data from FinancialModelingPrep ()
+# TODO # Get data from EODHD
+# https://eodhd.com/
+class EODHDHistoricDataHandler(BaseCSVDataHandler):
+    ...
+
+# TODO # Get data from FMP using Financialtoolkit API
+# https://github.com/bbalouki/FinanceToolkit
 class FMPHistoricDataHandler(BaseCSVDataHandler):
     ...
 
 
 class BaseFMPDataHanler(object):
+    """
+    This will serve as the base class for all other FMP data 
+    that is not historical data and does not have an OHLC structure.
+    """
     ...
 
 
 class FMPFundamentalDataHandler(BaseFMPDataHanler):
     ...
 
-# TODO Add other Handlers
+# TODO Add other Handlers for FMP
+
+
+# TODO Add data Handlers for Interactive Brokers

bbstrader/btengine/event.py

@@ -1,4 +1,5 @@
 from datetime import datetime
+from typing import Literal
 
 __all__ = [
     "Event",
@@ -53,9 +54,10 @@ class SignalEvent(Event):
                  strategy_id: int,
                  symbol: str,
                  datetime: datetime,
-                 signal_type: str,
+                 signal_type: Literal['LONG', 'SHORT', 'EXIT'],
                  quantity: int | float = 100,
-                 strength: int | float = 1.0
+                 strength: int | float = 1.0,
+                 price: int | float = None
                  ):
         """
         Initialises the SignalEvent.
@@ -66,10 +68,11 @@ class SignalEvent(Event):
 
             symbol (str): The ticker symbol, e.g. 'GOOG'.
             datetime (datetime): The timestamp at which the signal was generated.
-            signal_type (str): 'LONG' or 'SHORT'.
+            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.
         """
         self.type = 'SIGNAL'
         self.strategy_id = strategy_id
@@ -78,6 +81,7 @@ class SignalEvent(Event):
         self.signal_type = signal_type
         self.quantity = quantity
         self.strength = strength
+        self.price = price
 
 
 class OrderEvent(Event):
@@ -95,9 +99,10 @@ class OrderEvent(Event):
 
     def __init__(self,
                  symbol: str,
-                 order_type: str,
+                 order_type: Literal['MKT', 'LMT'],
                  quantity: int | float,
-                 direction: str
+                 direction: Literal['BUY', 'SELL'],
+                 price: int | float = None
                  ):
         """
         Initialises the order type, setting whether it is
@@ -109,20 +114,22 @@ class OrderEvent(Event):
             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.
         """
         self.type = 'ORDER'
         self.symbol = symbol
         self.order_type = order_type
         self.quantity = quantity
         self.direction = direction
+        self.price = price
 
         def print_order(self):
             """
             Outputs the values within the Order.
             """
             print(
-                "Order: Symbol=%s, Type=%s, Quantity=%s, Direction=%s" %
-                (self.symbol, self.order_type, self.quantity, self.direction)
+                "Order: Symbol=%s, Type=%s, Quantity=%s, Direction=%s, Price=%s" %
+                (self.symbol, self.order_type, self.quantity, self.direction, self.price)
             )
 
 
@@ -150,8 +157,8 @@ class FillEvent(Event):
                  symbol: str,
                  exchange: str,
                  quantity: int | float,
-                 direction: str,
-                 fill_cost: int | float,
+                 direction: Literal['BUY', 'SELL'],
+                 fill_cost: int | float | None,
                  commission: float | None = None
                  ):
         """
@@ -168,8 +175,8 @@ class FillEvent(Event):
             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 ('BUY' or 'SELL')
-            fill_cost (int | float): The holdings value in dollars.
+            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.
         """
         self.type = 'FILL'

bbstrader/btengine/execution.py

@@ -1,11 +1,13 @@
-import datetime
+from datetime import datetime
 from queue import Queue
 from abc import ABCMeta, abstractmethod
 from bbstrader.btengine.event import FillEvent, OrderEvent
+from bbstrader.metatrader.account import Account
 
 __all__ = [
     "ExecutionHandler",
-    "SimulatedExecutionHandler"
+    "SimulatedExecutionHandler",
+    "MT5ExecutionHandler"
 ]
 
 
@@ -51,7 +53,7 @@ class SimulatedExecutionHandler(ExecutionHandler):
     handler.
     """
 
-    def __init__(self, events: Queue):
+    def __init__(self, events: Queue, **kwargs):
         """
         Initialises the handler, setting the event queues
         up internally.
@@ -71,13 +73,71 @@ class SimulatedExecutionHandler(ExecutionHandler):
         """
         if event.type == 'ORDER':
             fill_event = FillEvent(
-                datetime.datetime.now(), event.symbol,
+                datetime.now(), event.symbol,
                 'ARCA', event.quantity, event.direction, None
             )
             self.events.put(fill_event)
 
-# TODO # Use in live execution
-
 
 class MT5ExecutionHandler(ExecutionHandler):
-    ...
+    def __init__(self, events: Queue, **kwargs):
+        """
+        """
+        self.events = events
+        self.account = Account()
+
+    def _estimate_total_fees(self, symbol, lot):
+        # TODO: Implement the calculation of fees based on the broker's fees
+        # https://www.metatrader5.com/en/terminal/help/trading/market_watch
+        # Calculate fees based on the broker's fees , swap and commission
+        return 0.0
+
+    def _calculate_lot(self, symbol, quantity, price):
+        FX = self.account.get_symbol_type(symbol) == 'FX'
+        COMD = self.account.get_symbol_type(symbol) == 'COMD'
+        FUT = self.account.get_symbol_type(symbol) == 'FUT'
+        CRYPTO = self.account.get_symbol_type(symbol) == 'CRYPTO'
+        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 = quantity
+        if COMD or FUT or CRYPTO and contract_size > 1:
+            lot = quantity  / contract_size
+        if FX:
+            lot = (quantity*price / contract_size)
+        return self._check_lot(symbol, lot)
+
+    def _check_lot(self, symbol, lot):
+        symbol_info =  self.account.get_symbol_info(symbol)
+        if lot < symbol_info.volume_min:
+            return symbol_info.volume_min
+        elif lot > symbol_info.volume_max:
+            return symbol_info.volume_max
+        return round(lot, 2)
+    
+    def execute_order(self, event: OrderEvent):
+        """
+        Executes an Order event by converting it into a Fill event.
+
+        Args:
+            event (OrderEvent): Contains an Event object with order information.
+        """
+        if event.type == 'ORDER':
+            symbol = event.symbol
+            direction = event.direction
+            quantity = event.quantity
+            price = event.price
+            lot = self._calculate_lot(symbol, quantity, price)
+            fees = self._estimate_total_fees(symbol, lot)
+            fill_event = FillEvent(
+                timeindex=datetime.now(), symbol=symbol,
+                exchange='MT5', quantity=quantity, direction=direction,
+                fill_cost=None, commission=fees
+            )
+            self.events.put(fill_event)
+
+
+class IBExecutionHandler(ExecutionHandler):
+    ...

bbstrader/btengine/performance.py

@@ -6,9 +6,11 @@ import yfinance as yf
 from scipy.stats import mstats
 import matplotlib.pyplot as plt
 from matplotlib.ticker import MaxNLocator
+import quantstats as qs
 
 import warnings
 warnings.filterwarnings("ignore")
+warnings.simplefilter(action='ignore', category=FutureWarning)
 sns.set_theme()
 
 __all__ = [
@@ -17,7 +19,8 @@ __all__ = [
     "create_sharpe_ratio",
     "create_sortino_ratio",
     "plot_returns_and_dd",
-    "plot_monthly_yearly_returns"
+    "plot_monthly_yearly_returns",
+    "show_qs_stats"
 ]
 
 
@@ -307,3 +310,33 @@ def plot_monthly_yearly_returns(df, title):
 
     # Show the plot
     plt.show()
+
+def show_qs_stats(equity_curve, benchmark, strategy_name):
+    """
+    Generate the full quantstats report for the strategy.
+
+    Args:
+        equity_curve (pd.DataFrame): 
+            The DataFrame containing the strategy returns and drawdowns.
+        benchmark (str): 
+            The ticker symbol of the benchmark to compare the strategy to.
+        strategy_name (str): The name of the strategy.
+    """
+    # Load the returns data
+    returns = equity_curve.copy()
+
+    # Drop duplicate index entries
+    returns = returns[~returns.index.duplicated(keep='first')]
+
+    # Extend pandas functionality with quantstats
+    qs.extend_pandas()
+
+    # Generate the full report with a benchmark
+    file = strategy_name.replace(' ', '_')
+    qs.reports.full(
+        returns['Returns'], mode='full', benchmark=benchmark)
+    qs.reports.html(
+        returns['Returns'], 
+        benchmark='SPY', 
+        output=f"{file}_report.html", 
+        title=strategy_name)

bbstrader/btengine/portfolio.py

@@ -6,10 +6,10 @@ from bbstrader.btengine.event import (
 )
 from bbstrader.btengine.data import DataHandler
 from bbstrader.btengine.performance import (
-    create_drawdowns, plot_performance,
-    create_sharpe_ratio, create_sortino_ratio,
+    create_drawdowns, plot_performance, show_qs_stats,
     plot_returns_and_dd, plot_monthly_yearly_returns
 )
+import quantstats as qs
 
 
 class Portfolio(object):
@@ -20,7 +20,7 @@ class Portfolio(object):
     sizing tools (such as the `Kelly Criterion`).
 
     The portfolio order management system is possibly the most complex component of 
-    an eventdriven backtester.  Its role is to keep track of all current market positions 
+    an event driven backtester. Its role is to keep track of all current market positions 
     as well as the market value of the positions (known as the "holdings"). 
     This is simply an estimate of the liquidation value of the position and is derived in part 
     from the data handling facility of the backtester.
@@ -95,7 +95,7 @@ class Portfolio(object):
         self.timeframe = kwargs.get("time_frame", "D1")
         self.trading_hours = kwargs.get("session_duration", 6.5)
         self.benchmark = kwargs.get('benchmark', 'SPY')
-        self.strategy_name = kwargs.get('strategy_name', 'Strategy')
+        self.strategy_name = kwargs.get('strategy_name', '')
         if self.timeframe not in self._tf_mapping():
             raise ValueError(
                 f"Timeframe not supported,"
@@ -227,10 +227,10 @@ class Portfolio(object):
             fill_dir = -1
 
         # Update holdings list with new quantities
-        fill_cost = self.bars.get_latest_bar_value(
+        price = self.bars.get_latest_bar_value(
             fill.symbol, "Adj Close"
         )
-        cost = fill_dir * fill_cost * fill.quantity
+        cost = fill_dir * price * fill.quantity
         self.current_holdings[fill.symbol] += cost
         self.current_holdings['Commission'] += fill.commission
         self.current_holdings['Cash'] -= (cost + fill.commission)
@@ -260,20 +260,21 @@ class Portfolio(object):
         direction = signal.signal_type
         quantity = signal.quantity
         strength = signal.strength
+        price = signal.price
         cur_quantity = self.current_positions[symbol]
 
         order_type = 'MKT'
         mkt_quantity = round(quantity * strength)
 
         if direction == 'LONG' and cur_quantity == 0:
-            order = OrderEvent(symbol, order_type, mkt_quantity, 'BUY')
+            order = OrderEvent(symbol, order_type, mkt_quantity, 'BUY', price)
         if direction == 'SHORT' and cur_quantity == 0:
-            order = OrderEvent(symbol, order_type, mkt_quantity, 'SELL')
+            order = OrderEvent(symbol, order_type, mkt_quantity, 'SELL', price)
 
         if direction == 'EXIT' and cur_quantity > 0:
-            order = OrderEvent(symbol, order_type, abs(cur_quantity), 'SELL')
+            order = OrderEvent(symbol, order_type, abs(cur_quantity), 'SELL', price)
         if direction == 'EXIT' and cur_quantity < 0:
-            order = OrderEvent(symbol, order_type, abs(cur_quantity), 'BUY')
+            order = OrderEvent(symbol, order_type, abs(cur_quantity), 'BUY', price)
 
         return order
 
@@ -305,9 +306,12 @@ class Portfolio(object):
         returns = self.equity_curve['Returns']
         pnl = self.equity_curve['Equity Curve']
 
-        sharpe_ratio = create_sharpe_ratio(returns, periods=self.tf)
-        sortino_ratio = create_sortino_ratio(returns, periods=self.tf)
-        drawdown, max_dd, dd_duration = create_drawdowns(pnl)
+        sharpe_ratio = qs.stats.sharpe(returns, periods=self.tf)
+        sortino_ratio = qs.stats.sortino(returns, periods=self.tf)
+        drawdown, _, _ = create_drawdowns(pnl)
+        max_dd = qs.stats.max_drawdown(returns)
+        dd_details = qs.stats.drawdown_details(drawdown)
+        dd_duration = dd_details['days'].max()
         self.equity_curve['Drawdown'] = drawdown
 
         stats = [
@@ -317,10 +321,16 @@ class Portfolio(object):
             ("Max Drawdown", f"{max_dd * 100.0:.2f}%"),
             ("Drawdown Duration", f"{dd_duration}")
         ]
-        self.equity_curve.to_csv('equity.csv')
+        now = datetime.now().strftime('%Y%m%d%H%M%S')
+        strategy_name = self.strategy_name.replace(' ', '_')
+        file =  f"{strategy_name}_{now}_equity.csv"
+        self.equity_curve.to_csv(file)
         plot_performance(self.equity_curve, self.strategy_name)
         plot_returns_and_dd(self.equity_curve,
                             self.benchmark, self.strategy_name)
+        qs.plots.monthly_heatmap(returns, savefig='monthly_heatmap.png')
         plot_monthly_yearly_returns(self.equity_curve, self.strategy_name)
+        show_qs_stats(self.equity_curve, self.benchmark, self.strategy_name)
 
         return stats
+

bbstrader/btengine/strategy.py

@@ -1,5 +1,5 @@
 from abc import ABCMeta, abstractmethod
-
+from typing import Dict, Union
 
 class Strategy(metaclass=ABCMeta):
     """
@@ -22,10 +22,11 @@ class Strategy(metaclass=ABCMeta):
     """
 
     @abstractmethod
-    def calculate_signals(self):
+    def calculate_signals(self, *args, **kwargs) -> Dict[str, Union[str, None]]:
         """
         Provides the mechanisms to calculate the list of signals.
+        This methods should return a dictionary of symbols and their respective signals.
         """
         raise NotImplementedError(
             "Should implement calculate_signals()"
-        )
+        )

bbstrader/metatrader/account.py

@@ -555,13 +555,19 @@ class Account(object):
 
         Raises:
             MT5TerminalError: A specific exception based on the error code.
+        
+        Notes:
+            The `time` property is converted to a `datetime` object using Broker server time.
         """
         try:
             symbol_info = mt5.symbol_info(symbol)
             if symbol_info is None:
                 return None
             else:
-                return SymbolInfo(**symbol_info._asdict())
+                symbol_info_dict = symbol_info._asdict()
+                time = datetime.fromtimestamp(symbol_info.time)
+                symbol_info_dict['time'] = time
+                return SymbolInfo(**symbol_info_dict)
         except Exception as e:
             msg = self._symbol_info_msg(symbol)
             raise_mt5_error(message=f"{e+msg}")
@@ -595,13 +601,19 @@ class Account(object):
 
         Raises:
             MT5TerminalError: A specific exception based on the error code.
+        
+        Notes:
+            The `time` property is converted to a `datetime` object using Broker server time.
         """
         try:
             tick_info = mt5.symbol_info_tick(symbol)
             if tick_info is None:
                 return None
             else:
-                return TickInfo(**tick_info._asdict())
+                info_dict = tick_info._asdict()
+                time = datetime.fromtimestamp(tick_info.time)
+                info_dict['time'] = time
+                return TickInfo(**info_dict)
         except Exception as e:
             msg = self._symbol_info_msg(symbol)
             raise_mt5_error(message=f"{e+msg}")
@@ -770,7 +782,7 @@ class Account(object):
         else:
             positions = mt5.positions_get()
 
-        if positions is None:
+        if positions is None or len(positions) == 0:
             return None
         if to_df:
             df = pd.DataFrame(list(positions), columns=positions[0]._asdict())
@@ -873,7 +885,7 @@ class Account(object):
         else:
             position_deals = mt5.history_deals_get(date_from, date_to)
 
-        if position_deals is None:
+        if position_deals is None or len(position_deals) == 0:
             return None
 
         df = pd.DataFrame(list(position_deals),
@@ -949,7 +961,7 @@ class Account(object):
         else:
             orders = mt5.orders_get()
 
-        if orders is None:
+        if orders is None or len(orders) == 0:
             return None
 
         if to_df:
@@ -1052,7 +1064,7 @@ class Account(object):
         else:
             history_orders = mt5.history_orders_get(date_from, date_to)
 
-        if history_orders is None:
+        if history_orders is None or len(history_orders) == 0:
             return None
 
         df = pd.DataFrame(list(history_orders),

bbstrader/metatrader/rates.py

@@ -21,6 +21,15 @@ class Rates(object):
     flexibility in retrieving data either by specifying a starting position
     and count of bars or by providing a specific date range.
 
+    Notes:
+        1. Befor using this class, ensure that the `Max bars in chart` in you terminal
+        is set to a value that is greater than the number of bars you want to retrieve
+        or just set it to Unlimited.
+        In your MT5 terminal, go to `Tools` -> `Options` -> `Charts` -> `Max bars in chart`.
+        
+        2. The `get_open, get_high, get_low, get_close, get_adj_close, get_returns,
+        get_volume` properties return data in  Broker's timezone.
+
     Example:
         >>> rates = Rates("EURUSD", "1h")
         >>> df = rates.get_historical_data(
@@ -62,8 +71,14 @@ class Rates(object):
         self.start_pos = self._get_start_pos(start_pos, time_frame)
         self.count = count
         self._mt5_initialized()
-        self.data = self.get_rates_from_pos()
+        self.__data = self.get_rates_from_pos()
+
 
+    def _mt5_initialized(self):
+        """Ensures the MetaTrader 5 Terminal is initialized."""
+        if not Mt5.initialize():
+            raise_mt5_error(message=INIT_MSG)
+    
     def _get_start_pos(self, index, time_frame):
         if isinstance(index, int):
             start_pos = index
@@ -112,11 +127,6 @@ class Rates(object):
             )
         return TIMEFRAMES[time_frame]
 
-    def _mt5_initialized(self):
-        """Ensures the MetaTrader 5 Terminal is initialized."""
-        if not Mt5.initialize():
-            raise_mt5_error(message=INIT_MSG)
-
     def _fetch_data(
         self, start: Union[int, datetime],
         count: Union[int, datetime]
@@ -160,6 +170,13 @@ class Rates(object):
         Returns:
             Union[pd.DataFrame, None]: A DataFrame containing historical
             data if successful, otherwise None.
+        
+        Raises:
+            ValueError: If `start_pos` or `count` is not provided during
+                initialization.
+
+        Notes:
+            The Datetime for this method is in Broker's timezone.
         """
         if self.start_pos is None or self.count is None:
             raise ValueError(
@@ -171,23 +188,23 @@ class Rates(object):
     
     @property
     def get_open(self):
-        return self.data['Open']
+        return self.__data['Open']
         
     @property
     def get_high(self):
-        return self.data['High']
+        return self.__data['High']
     
     @property
     def get_low(self):
-        return self.data['Low']
+        return self.__data['Low']
     
     @property
     def get_close(self):
-        return self.data['Close']
+        return self.__data['Close']
 
     @property
     def get_adj_close(self):
-        return self.data['Adj Close']
+        return self.__data['Adj Close']
     
     @property
     def get_returns(self):
@@ -202,7 +219,7 @@ class Rates(object):
         It calculates fractional change (also known as `per unit change or relative change`) 
         and `not percentage change`. If you need the percentage change, multiply these values by 100.
         """
-        data = self.data.copy()
+        data = self.__data.copy()
         data['Returns'] =  data['Adj Close'].pct_change()
         data = data.dropna()
         return data['Returns']
@@ -230,6 +247,12 @@ class Rates(object):
         Returns:
             Union[pd.DataFrame, None]: A DataFrame containing historical data
                 if successful, otherwise None.
+        
+        Raises:
+            ValueError: If the starting date is greater than the ending date.
+        
+        Notes:
+            The Datetime for this method is in UTC timezone.
         """
         df = self._fetch_data(date_from, date_to)
         if save_csv and df is not None: