bbstrader 0.3.5__py3-none-any.whl → 0.3.6__py3-none-any.whl

bbstrader/__init__.py

@@ -7,7 +7,14 @@ __author__ = "Bertin Balouki SIMYELI"
 __copyright__ = "2023-2025 Bertin Balouki SIMYELI"
 __email__ = "bertin@bbstrader.com"
 __license__ = "MIT"
-__version__ = "0.3.5"
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("bbstrader")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
 
 from bbstrader import compat  # noqa: F401
 from bbstrader import core  # noqa: F401
@@ -17,3 +24,5 @@ from bbstrader import models  # noqa: F401
 from bbstrader import trading  # noqa: F401
 from bbstrader import tseries  # noqa: F401
 from bbstrader.config import config_logger  # noqa: F401
+
+version = __version__

bbstrader/__main__.py

@@ -10,6 +10,7 @@ from bbstrader.btengine.scripts import backtest
 from bbstrader.core.scripts import send_news_feed
 from bbstrader.metatrader.scripts import copy_trades
 from bbstrader.trading.scripts import execute_strategy
+from . import __author__, __version__
 
 
 class _Module(Enum):
@@ -50,6 +51,10 @@ def main():
     if ("-h" in sys.argv or "--help" in sys.argv) and args.run is None:
         print(Fore.WHITE + USAGE_TEXT)
         sys.exit(0)
+    if ("-v" in sys.argv or "--version" in sys.argv):
+        print(Fore.GREEN + f"bbstrader version {__version__}")
+        print(Fore.WHITE + f"bbstrader maintained and supported by {__author__}")
+        sys.exit(0)
     try:
         match args.run:
             case _Module.COPIER.value:

bbstrader/apps/_copier.py

@@ -431,7 +431,7 @@ class TradeCopierApp(object):
                 or not dest["path"].get()
             ):
                 messagebox.showerror(
-                    "Error", f"Destination account {i+1} details are incomplete."
+                    "Error", f"Destination account {i + 1} details are incomplete."
                 )
                 return False
             if (
@@ -440,7 +440,7 @@ class TradeCopierApp(object):
             ):
                 messagebox.showerror(
                     "Error",
-                    f"Value is required for mode '{dest['mode'].get()}' in Destination {i+1}.",
+                    f"Value is required for mode '{dest['mode'].get()}' in Destination {i + 1}.",
                 )
                 return False
             try:
@@ -451,7 +451,7 @@ class TradeCopierApp(object):
             except ValueError:
                 messagebox.showerror(
                     "Error",
-                    f"Invalid Value or Slippage for Destination {i+1}. "
+                    f"Invalid Value or Slippage for Destination {i + 1}. "
                     "Must be a number (Slippage must be an integer).",
                 )
                 return False

bbstrader/btengine/strategy.py

@@ -2,7 +2,7 @@ import string
 from abc import ABCMeta, abstractmethod
 from datetime import datetime
 from queue import Queue
-from typing import Dict, List, Literal, Union
+from typing import Callable, Dict, List, Literal, Union
 
 import numpy as np
 import pandas as pd
@@ -11,19 +11,19 @@ from loguru import logger
 
 from bbstrader.btengine.data import DataHandler
 from bbstrader.btengine.event import Events, FillEvent, SignalEvent
-from bbstrader.metatrader.trade import generate_signal, TradeAction 
 from bbstrader.config import BBSTRADER_DIR
 from bbstrader.metatrader import (
     Account,
     AdmiralMarktsGroup,
     MetaQuotes,
     PepperstoneGroupLimited,
-    TradeOrder,
     Rates,
-    TradeSignal, 
+    SymbolType,
+    TradeOrder,
+    TradeSignal,
     TradingMode,
-    SymbolType
 )
+from bbstrader.metatrader.trade import TradeAction, generate_signal
 from bbstrader.models.optimization import optimized_weights
 
 __all__ = ["Strategy", "MT5Strategy"]
@@ -79,10 +79,11 @@ class MT5Strategy(Strategy):
     It is recommanded that every strategy specfic method to be a private method
     in order to avoid naming collusion.
     """
+
     tf: str
     id: int
     ID: int
-    
+
     max_trades: Dict[str, int]
     risk_budget: Dict[str, float] | str | None
 
@@ -116,8 +117,10 @@ class MT5Strategy(Strategy):
         self.symbols = symbol_list
         self.mode = mode
         if self.mode not in [TradingMode.BACKTEST, TradingMode.LIVE]:
-            raise ValueError(f"Mode must be an instance of {type(TradingMode)} not {type(self.mode)}")
-        
+            raise ValueError(
+                f"Mode must be an instance of {type(TradingMode)} not {type(self.mode)}"
+            )
+
         self.risk_budget = self._check_risk_budget(**kwargs)
 
         self.max_trades = kwargs.get("max_trades", {s: 1 for s in self.symbols})
@@ -189,7 +192,7 @@ class MT5Strategy(Strategy):
     def _initialize_portfolio(self):
         self._orders = {}
         self._positions = {}
-        self._trades =  {}
+        self._trades = {}
         for symbol in self.symbols:
             self._positions[symbol] = {}
             self._orders[symbol] = {}
@@ -254,30 +257,40 @@ class MT5Strategy(Strategy):
     def signal(self, signal: int, symbol: str) -> TradeSignal:
         """
         Generate a ``TradeSignal`` object based on the signal value.
-        Args:
-            signal : An integer value representing the signal type:
-                     0: BUY
-                     1: SELL
-                     2: EXIT_LONG
-                     3: EXIT_SHORT
-                     4: EXIT_ALL_POSITIONS
-                     5: EXIT_ALL_ORDERS
-                     6: EXIT_STOP
-                     7: EXIT_LIMIT
-
-            symbol : The symbol for the trade.
-
-        Returns:
-            TradeSignal : A ``TradeSignal`` object representing the trade signal.
-
-        Note:
-            This generate only common signals. For more complex signals, use `generate_signal` directly.
 
-        Raises:
-            ValueError : If the signal value is not between 0 and 7.
+        Parameters
+        ----------
+        signal : int
+            An integer value representing the signal type:
+            * 0: BUY
+            * 1: SELL
+            * 2: EXIT_LONG
+            * 3: EXIT_SHORT
+            * 4: EXIT_ALL_POSITIONS
+            * 5: EXIT_ALL_ORDERS
+            * 6: EXIT_STOP
+            * 7: EXIT_LIMIT
+        symbol : str
+            The symbol for the trade.
+
+        Returns
+        -------
+        TradeSignal
+            A ``TradeSignal`` object representing the trade signal.
+
+        Raises
+        ------
+        ValueError
+            If the signal value is not between 0 and 7.
+
+        Notes
+        -----
+        This generates only common signals. For more complex signals, use
+        ``generate_signal`` directly.
         """
+
         signal_id = getattr(self, "id", None) or getattr(self, "ID")
-        
+
         match signal:
             case 0:
                 return generate_signal(signal_id, symbol, TradeAction.BUY)
@@ -288,7 +301,9 @@ class MT5Strategy(Strategy):
             case 3:
                 return generate_signal(signal_id, symbol, TradeAction.EXIT_SHORT)
             case 4:
-                return generate_signal(signal_id, symbol, TradeAction.EXIT_ALL_POSITIONS)
+                return generate_signal(
+                    signal_id, symbol, TradeAction.EXIT_ALL_POSITIONS
+                )
             case 5:
                 return generate_signal(signal_id, symbol, TradeAction.EXIT_ALL_ORDERS)
             case 6:
@@ -296,8 +311,64 @@ class MT5Strategy(Strategy):
             case 7:
                 return generate_signal(signal_id, symbol, TradeAction.EXIT_LIMIT)
             case _:
-                raise ValueError(f"Invalid signal value: {signal}. Must be an integer between 0 and 7.")
+                raise ValueError(
+                    f"Invalid signal value: {signal}. Must be an integer between 0 and 7."
+                )
 
+    def send_trade_repport(self, perf_analyzer: Callable, **kwargs):
+        """
+        Generates and sends a trade report message containing performance metrics for the current strategy.
+        This method retrieves the trade history for the current account, filters it by the strategy's ID,
+        computes performance metrics using the provided `perf_analyzer` callable, and formats the results
+        into a message. The message includes account information, strategy details, a timestamp, and
+        performance metrics. The message is then sent via Telegram using the specified bot token and chat ID.
+
+        Args:
+            perf_analyzer (Callable): A function or callable object that takes the filtered trade history
+                (as a DataFrame) and additional keyword arguments, and returns a DataFrame of performance metrics.
+            **kwargs: Additional keyword arguments, which may include
+                - Any other param requires by ``perf_analyzer``
+        """
+        
+        from bbstrader.trading.utils import send_message
+
+        history = self.account.get_trades_history()
+        if history is None:
+            return
+
+        ID = getattr(self, "id", None) or getattr(self, "ID")
+        history = history[history["magic"] == ID]
+        performance = perf_analyzer(history, **kwargs)
+
+        account = self.kwargs.get("account", "MT5 Account")
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+        header = (
+            f"==== TRADE REPORT =====\n\n"
+            f"ACCOUNT: {account}\n"
+            f"STRATEGY: {self.NAME}\n"
+            f"ID: {ID}\n"
+            f"DESCRIPTION: {self.DESCRIPTION}\n"
+            f"TIMESTAMP: {timestamp}\n\n"
+            f"📊 PERFORMANCE:\n"
+        )
+        metrics = performance.iloc[0].to_dict()
+
+        lines = []
+        for key, value in metrics.items():
+            if isinstance(value, float):
+                value = round(value, 4)
+            lines.append(f"{key:<15}: {value}")
+
+        performance_str = "\n".join(lines)
+        message = f"{header}{performance_str}"
+
+        send_message(
+            message=message,
+            telegram=True,
+            token=self.kwargs.get("bot_token"),
+            chat_id=self.kwargs.get("chat_id"),
+        )
 
     def perform_period_end_checks(self, *args, **kwargs):
         """
@@ -831,8 +902,10 @@ class MT5Strategy(Strategy):
             )
             return prices
         return np.array([])
-    
-    def get_active_orders(self, symbol: str, strategy_id: int, order_type: int = None) -> List[TradeOrder]:
+
+    def get_active_orders(
+        self, symbol: str, strategy_id: int, order_type: int = None
+    ) -> List[TradeOrder]:
         """
         Get the active orders for a given symbol and strategy.
 
@@ -850,7 +923,9 @@ class MT5Strategy(Strategy):
         Returns:
             List[TradeOrder] : A list of active orders for the given symbol and strategy.
         """
-        orders = [o for o in self.orders if o.symbol == symbol and o.magic == strategy_id]
+        orders = [
+            o for o in self.orders if o.symbol == symbol and o.magic == strategy_id
+        ]
         if order_type is not None and len(orders) > 0:
             orders = [o for o in orders if o.type == order_type]
         return orders
@@ -866,7 +941,7 @@ class MT5Strategy(Strategy):
         elif len(prices) in range(2, self.max_trades[asset] + 1):
             price = np.mean(prices)
         if price is not None:
-            if position == 0: 
+            if position == 0:
                 return self.calculate_pct_change(ask, price) >= th
             elif position == 1:
                 return self.calculate_pct_change(bid, price) <= -th
@@ -920,7 +995,7 @@ class MT5Strategy(Strategy):
         Returns:
             mt5_equivalent : The MetaTrader 5 equivalent symbols for the symbols in the list.
         """
-        
+
         account = Account(**kwargs)
         mt5_symbols = account.get_symbols(symbol_type=symbol_type)
         mt5_equivalent = []
@@ -933,7 +1008,7 @@ class MT5Strategy(Strategy):
                         mt5_equivalent.append(s)
 
         def _get_pepperstone_symbols():
-             for s in mt5_symbols:
+            for s in mt5_symbols:
                 for symbol in symbols:
                     if s.split(".")[0] == symbol:
                         mt5_equivalent.append(s)

bbstrader/metatrader/account.py

@@ -157,22 +157,38 @@ def check_mt5_connection(
     """
     Initialize the connection to the MetaTrader 5 terminal.
 
-    Args:
-        path (str, optional): The path to the MetaTrader 5 terminal executable file.
-            Defaults to None (e.g., "C:/Program Files/MetaTrader 5/terminal64.exe").
-        login (int, optional): The login ID of the trading account. Defaults to None.
-        password (str, optional): The password of the trading account. Defaults to None.
-        server (str, optional): The name of the trade server to which the client terminal is connected.
-            Defaults to None.
-        timeout (int, optional): Connection timeout in milliseconds. Defaults to 60_000.
-        portable (bool, optional): If True, the portable mode of the terminal is used.
-            Defaults to False (See https://www.metatrader5.com/en/terminal/help/start_advanced/start#portable).
-
-    Notes:
-        If you want to lunch multiple terminal instances:
-        - Follow these instructions to lunch each terminal in portable mode first:
-            https://www.metatrader5.com/en/terminal/help/start_advanced/start#configuration_file
+    Parameters
+    ----------
+    path : str, optional
+        Path to the MetaTrader 5 terminal executable file.
+        Defaults to ``None`` (e.g., ``"C:/Program Files/MetaTrader 5/terminal64.exe"``).
+    login : int, optional
+        The login ID of the trading account. Defaults to ``None``.
+    password : str, optional
+        The password of the trading account. Defaults to ``None``.
+    server : str, optional
+        The name of the trade server to which the client terminal is connected.
+        Defaults to ``None``.
+    timeout : int, optional
+        Connection timeout in milliseconds. Defaults to ``60_000``.
+    portable : bool, optional
+        If ``True``, the portable mode of the terminal is used.
+        Defaults to ``False``.
+        See: https://www.metatrader5.com/en/terminal/help/start_advanced/start#portable
+
+    Returns
+    -------
+    bool
+        ``True`` if the connection is successfully established, otherwise ``False``.
+
+    Notes
+    -----
+    If you want to launch multiple terminal instances:
+
+    * First, launch each terminal in **portable mode**.
+    * See instructions: https://www.metatrader5.com/en/terminal/help/start_advanced/start#configuration_file
     """
+
     if login is not None and server is not None:
         account_info = mt5.account_info()
         if account_info is not None:
@@ -201,9 +217,9 @@ def check_mt5_connection(
         else:
             init = mt5.initialize()
         if not init:
-            raise_mt5_error(INIT_MSG)
+            raise_mt5_error(str(mt5.last_error()) + INIT_MSG)
     except Exception:
-        raise_mt5_error(INIT_MSG)
+        raise_mt5_error(str(mt5.last_error()) + INIT_MSG)
     return init
 
 
@@ -1209,17 +1225,26 @@ class Account(object):
     def get_market_book(self, symbol: str) -> Tuple[BookInfo]:
         """
         Get the Market Depth content for a specific symbol.
-        Args:
-            symbol (str): Financial instrument name. Required unnamed parameter.
-                The symbol name should be specified in the same format as in the Market Watch window.
-
-        Returns:
-            The Market Depth content as a tuple from BookInfo entries featuring order type, price and volume in lots.
-            Return None in case of an error.
 
-        Raises:
-            MT5TerminalError: A specific exception based on the error code.
+        Parameters
+        ----------
+        symbol : str
+            Financial instrument name. The symbol should be specified in the
+            same format as in the Market Watch window.
+
+        Returns
+        -------
+        tuple of BookInfo or None
+            The Market Depth content as a tuple of ``BookInfo`` entries
+            (order type, price, and volume in lots).  
+            Returns ``None`` in case of an error.
+
+        Raises
+        ------
+        MT5TerminalError
+            A specific exception based on the error code.
         """
+
         try:
             book = mt5.market_book_get(symbol)
             return (

bbstrader/metatrader/analysis.py

@@ -57,23 +57,37 @@ def display_volume_profile(
 
     This function retrieves historical price and volume data for a given symbol and
     plots a vertical volume profile chart showing the volume distribution across 
-    price levels. It highlights key levels such as:
-        - Point of Control (POC): Price level with the highest traded volume.
-        - Value Area High (VAH): Upper bound of the value area.
-        - Value Area Low (VAL): Lower bound of the value area.
-        - Current Price: Latest bid price from MetaTrader 5.
-
-    Args:
-        symbol (str): Market symbol (e.g., "AAPL", "EURUSD").
-        path (str): Path to the historical data see ``bbstrader.metatrader.account.check_mt5_connection()``.
-        timeframe (str, optional): Timeframe for each candle (default is "1m").
-        bars (int, optional): Number of historical bars to fetch (default is 1440).
-        bins (int, optional): Number of price bins for volume profile calculation (default is 100).
-        va_percentage (float, optional): Percentage of total volume to define the value area (default is 0.7).
-
-    Returns:
-        None: Displays a matplotlib chart of the volume profile.
+    price levels.
+
+    Highlights
+    ----------
+    * **Point of Control (POC)**: Price level with the highest traded volume.
+    * **Value Area High (VAH)**: Upper bound of the value area.
+    * **Value Area Low (VAL)**: Lower bound of the value area.
+    * **Current Price**: Latest bid price from MetaTrader 5.
+
+    Parameters
+    ----------
+    symbol : str
+        Market symbol (e.g., ``"AAPL"``, ``"EURUSD"``).
+    path : str
+        Path to the historical data. See 
+        ``bbstrader.metatrader.account.check_mt5_connection()``.
+    timeframe : str, optional
+        Timeframe for each candle. Default is ``"1m"``.
+    bars : int, optional
+        Number of historical bars to fetch. Default is ``1440``.
+    bins : int, optional
+        Number of price bins for volume profile calculation. Default is ``100``.
+    va_percentage : float, optional
+        Percentage of total volume to define the value area. Default is ``0.7``.
+
+    Returns
+    -------
+    None
+        Displays a matplotlib chart of the volume profile.
     """
+
     check_mt5_connection(path=path)
     df = _get_data(symbol, TIMEFRAMES[timeframe], bars)
     if df.empty:

bbstrader/metatrader/copier.py

@@ -1177,29 +1177,45 @@ def RunCopier(
     shutdown_event=None,
     log_queue=None,
 ):
-    """Initializes and runs a TradeCopier instance in a single process.
+    """
+    Initialize and run a TradeCopier instance in a single process.
 
     This function serves as a straightforward wrapper to start a copying session
     that handles one source account and one or more destination accounts
-    *sequentially* within the same thread. It does not create any new processes itself.
+    sequentially within the same thread. It does not create any new processes itself.
 
-    This is useful for:
-    - Simpler, command-line based use cases.
-    - Scenarios where parallelism is not required.
-    - As the target for `RunMultipleCopier`, where each process handles a
+    Use Cases
+    ---------
+    * Simpler, command-line based use cases.
+    * Scenarios where parallelism is not required.
+    * As the target for ``RunMultipleCopier``, where each process handles a
       full source-to-destinations session.
 
-    Args:
-        source (dict): Configuration dictionary for the source account.
-        destinations (list): A list of configuration dictionaries, one for each
-            destination account to be processed sequentially.
-        sleeptime (float): The time in seconds to wait after completing a full
-            cycle through all destinations.
-        start_time (str): The time of day to start copying (e.g., "08:00").
-        end_time (str): The time of day to stop copying (e.g., "22:00").
-        custom_logger: An optional custom logger instance.
-        shutdown_event (multiprocessing.Event): An event to signal shutdown.
-        log_queue (multiprocessing.Queue): A queue for log messages.
+    Parameters
+    ----------
+    source : dict
+        Configuration dictionary for the source account.
+    destinations : list
+        A list of configuration dictionaries, one for each
+        destination account to be processed sequentially.
+    sleeptime : float
+        The time in seconds to wait after completing a full
+        cycle through all destinations.
+    start_time : str
+        The time of day to start copying (e.g., ``"08:00"``).
+    end_time : str
+        The time of day to stop copying (e.g., ``"22:00"``).
+    custom_logger : logging.Logger, optional
+        An optional custom logger instance.
+    shutdown_event : multiprocessing.Event, optional
+        An event to signal shutdown.
+    log_queue : multiprocessing.Queue, optional
+        A queue for log messages.
+
+    Returns
+    -------
+    None
+        Runs until stopped via ``shutdown_event`` or external interruption.
     """
     copier = TradeCopier(
         source,
@@ -1224,7 +1240,8 @@ def RunMultipleCopier(
     custom_logger=None,
     log_queue=None,
 ):
-    """Manages multiple, independent trade copying sessions in parallel.
+    """
+    Manage multiple, independent trade copying sessions in parallel.
 
     This function acts as a high-level manager that takes a list of account
     setups and creates a separate, dedicated process for each one. Each process
@@ -1232,28 +1249,46 @@ def RunMultipleCopier(
     destination accounts.
 
     The parallelism occurs at the **source account level**. Within each spawned
-    process, the destinations for that source are handled sequentially by `RunCopier`.
-
-    Example `accounts` structure:
-    [
-        { "source": {...}, "destinations": [{...}, {...}] },  # -> Process 1
-        { "source": {...}, "destinations": [{...}] }          # -> Process 2
-    ]
-
-    Args:
-        accounts (List[dict]): A list of account configurations. Each item in the
-            list must be a dictionary with a 'source' key and a 'destinations' key.
-        sleeptime (float): The sleep time passed down to each `RunCopier` process.
-        start_delay (float): A delay in seconds between starting each new process.
-            This helps prevent resource contention by staggering the initialization
-            of multiple MetaTrader 5 terminals.
-        start_time (str): The start time passed down to each `RunCopier` process.
-        end_time (str): The end time passed down to each `RunCopier` process.
-        shutdown_event (multiprocessing.Event): An event to signal shutdown to all
-            child processes.
-        custom_logger: An optional custom logger instance.
-        log_queue (multiprocessing.Queue): A queue for aggregating log messages
-            from all child processes.
+    process, the destinations for that source are handled sequentially by
+    ``RunCopier``.
+
+    Example
+    -------
+    An example ``accounts`` structure:
+
+    .. code-block:: python
+
+        accounts = [
+            {"source": {...}, "destinations": [{...}, {...}]},  # -> Process 1
+            {"source": {...}, "destinations": [{...}]}          # -> Process 2
+        ]
+
+    Parameters
+    ----------
+    accounts : list of dict
+        A list of account configurations. Each item must be a dictionary with
+        a ``source`` key and a ``destinations`` key.
+    sleeptime : float, optional
+        The sleep time passed down to each ``RunCopier`` process.
+    start_delay : float, optional
+        A delay in seconds between starting each new process.
+        Helps prevent resource contention by staggering the initialization of
+        multiple MetaTrader 5 terminals.
+    start_time : str, optional
+        The start time passed down to each ``RunCopier`` process.
+    end_time : str, optional
+        The end time passed down to each ``RunCopier`` process.
+    shutdown_event : multiprocessing.Event, optional
+        An event to signal shutdown to all child processes.
+    custom_logger : logging.Logger, optional
+        An optional custom logger instance.
+    log_queue : multiprocessing.Queue, optional
+        A queue for aggregating log messages from all child processes.
+
+    Returns
+    -------
+    None
+        Runs until stopped via ``shutdown_event`` or external interruption.
     """
     processes = []