bbstrader 0.3.5__tar.gz → 0.3.6__tar.gz

{bbstrader-0.3.5/bbstrader.egg-info → bbstrader-0.3.6}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: bbstrader
-Version: 0.3.5
+Version: 0.3.6
 Summary: Simplified Investment & Trading Toolkit
-Home-page: https://github.com/bbalouki/bbstrader
-Download-URL: https://pypi.org/project/bbstrader/
-Author: Bertin Balouki SIMYELI
-Author-email: <bertin@bbstrader.com>
-Maintainer: Bertin Balouki SIMYELI
-License: MIT
+Author-email: Bertin Balouki SIMYELI <bertin@bbstrader.com>
+Maintainer-email: Bertin Balouki SIMYELI <bertin@bbstrader.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bbalouki/bbstrader
+Project-URL: Download, https://pypi.org/project/bbstrader/
 Project-URL: Documentation, https://bbstrader.readthedocs.io/en/latest/
 Project-URL: Source Code, https://github.com/bbalouki/bbstrader
 Keywords: Finance,Toolkit,Financial,Analysis,Fundamental,Quantitative,Database,Equities,Currencies,Economics,ETFs,Funds,Indices,Moneymarkets,Commodities,Futures,CFDs,Derivatives,Trading,Investing,Portfolio,Optimization,Performance
@@ -19,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: alphalens-reloaded>=0.4.6
@@ -58,21 +58,7 @@ Requires-Dist: vaderSentiment>=3.3.2
 Requires-Dist: yfinance>=0.2.65
 Provides-Extra: mt5
 Requires-Dist: MetaTrader5; extra == "mt5"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: download-url
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
 Dynamic: license-file
-Dynamic: maintainer
-Dynamic: project-url
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: summary
 
 # Simplified Investment & Trading Toolkit
 [![Documentation Status](https://readthedocs.org/projects/bbstrader/badge/?version=latest)](https://bbstrader.readthedocs.io/en/latest/?badge=latest)

{bbstrader-0.3.5 → bbstrader-0.3.6}/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-0.3.5 → bbstrader-0.3.6}/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-0.3.5 → bbstrader-0.3.6}/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-0.3.5 → bbstrader-0.3.6}/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-0.3.5 → bbstrader-0.3.6}/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-0.3.5 → bbstrader-0.3.6}/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: