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

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 = []
 

bbstrader/metatrader/trade.py

@@ -95,27 +95,16 @@ class TradeSignal:
     """
     Represents a trading signal generated by a trading system or strategy.
 
+    Notes
+    -----
     Attributes:
-        id (int):
-            A unique identifier for the trade signal or the strategy.
 
-        symbol (str):
-            The trading symbol (e.g., stock ticker, forex pair, crypto asset)
-            related to the signal.
-
-        action (TradeAction):
-            The trading action to perform.
-            Must be an instance of the `TradeAction` enum (e.g., BUY, SELL).
-
-        price (float, optional):
-            The price at which the trade should be executed.
-
-        stoplimit (float, optional):
-            A stop-limit price for the trade.
-            Must not be set without specifying a price.
-
-        comment (str, optional):
-            An optional comment or description related to the trade signal.
+    - id (int): A unique identifier for the trade signal or the strategy.
+    - symbol (str): The trading symbol (e.g., stock ticker, forex pair, crypto asset).
+    - action (TradeAction): The trading action to perform. Must be an instance of the ``TradeAction`` enum (e.g., BUY, SELL).
+    - price (float, optional): The price at which the trade should be executed.
+    - stoplimit (float, optional): A stop-limit price for the trade. Must not be set without specifying a price.
+    - comment (str, optional): An optional comment or description related to the trade signal.
     """
 
     id: int
@@ -781,14 +770,14 @@ class Trade(RiskManagement):
             self.check_order(request)
             result = self.send_order(request)
         except Exception as e:
-            msg = trade_retcode_message(result.retcode)  if result else "N/A"
+            msg = trade_retcode_message(result.retcode) if result else "N/A"
             LOGGER.error(f"Trade Order Request, {msg}{addtionnal}, {e}")
         if result and result.retcode != Mt5.TRADE_RETCODE_DONE:
             if result.retcode == Mt5.TRADE_RETCODE_INVALID_FILL:  # 10030
                 for fill in FILLING_TYPE:
                     request["type_filling"] = fill
                     result = self.send_order(request)
-                    if result and  result.retcode == Mt5.TRADE_RETCODE_DONE:
+                    if result and result.retcode == Mt5.TRADE_RETCODE_DONE:
                         break
             elif result.retcode == Mt5.TRADE_RETCODE_INVALID_VOLUME:  # 10014
                 new_volume = int(request["volume"])
@@ -812,14 +801,14 @@ class Trade(RiskManagement):
                         self.check_order(request)
                         result = self.send_order(request)
                     except Exception as e:
-                        msg = trade_retcode_message(result.retcode)  if result else "N/A"
+                        msg = trade_retcode_message(result.retcode) if result else "N/A"
                         LOGGER.error(f"Trade Order Request, {msg}{addtionnal}, {e}")
-                    if result and  result.retcode == Mt5.TRADE_RETCODE_DONE:
+                    if result and result.retcode == Mt5.TRADE_RETCODE_DONE:
                         break
                     tries += 1
         # Print the result
-        if result and  result.retcode == Mt5.TRADE_RETCODE_DONE:
-            msg = trade_retcode_message(result.retcode) 
+        if result and result.retcode == Mt5.TRADE_RETCODE_DONE:
+            msg = trade_retcode_message(result.retcode)
             LOGGER.info(f"Trade Order {msg}{addtionnal}")
             if type != "BMKT" or type != "SMKT":
                 self.opened_orders.append(result.order)
@@ -855,7 +844,7 @@ class Trade(RiskManagement):
                             LOGGER.info(pos_info)
             return True
         else:
-            msg = trade_retcode_message(result.retcode)  if result else "N/A"
+            msg = trade_retcode_message(result.retcode) if result else "N/A"
             LOGGER.error(
                 f"Unable to Open Position, RETCODE={result.retcode}: {msg}{addtionnal}"
             )
@@ -1332,10 +1321,10 @@ class Trade(RiskManagement):
             self.check_order(request)
             result = self.send_order(request)
         except Exception as e:
-            msg = trade_retcode_message(result.retcode)   if result else "N/A"
+            msg = trade_retcode_message(result.retcode) if result else "N/A"
             LOGGER.error(f"Break-Even Order Request, {msg}{addtionnal}, Error: {e}")
-        if result and   result.retcode != Mt5.TRADE_RETCODE_DONE:
-            msg = trade_retcode_message(result.retcode)  
+        if result and result.retcode != Mt5.TRADE_RETCODE_DONE:
+            msg = trade_retcode_message(result.retcode)
             if result.retcode != Mt5.TRADE_RETCODE_NO_CHANGES:
                 LOGGER.error(
                     f"Break-Even Order Request, Position: #{tiket}, RETCODE={result.retcode}: {msg}{addtionnal}"
@@ -1350,15 +1339,15 @@ class Trade(RiskManagement):
                         self.check_order(request)
                         result = self.send_order(request)
                     except Exception as e:
-                        msg = trade_retcode_message(result.retcode)   if result else "N/A"
+                        msg = trade_retcode_message(result.retcode) if result else "N/A"
                         LOGGER.error(
                             f"Break-Even Order Request, {msg}{addtionnal}, Error: {e}"
                         )
-                    if result and   result.retcode == Mt5.TRADE_RETCODE_DONE:
+                    if result and result.retcode == Mt5.TRADE_RETCODE_DONE:
                         break
                 tries += 1
-        if result and   result.retcode == Mt5.TRADE_RETCODE_DONE:
-            msg = trade_retcode_message(result.retcode) 
+        if result and result.retcode == Mt5.TRADE_RETCODE_DONE:
+            msg = trade_retcode_message(result.retcode)
             LOGGER.info(f"Break-Even Order {msg}{addtionnal}")
             info = f"Stop loss set to Break-even, Position: #{tiket}, Symbol: {self.symbol}, Price: @{round(price, 5)}"
             LOGGER.info(info)
@@ -1434,7 +1423,7 @@ class Trade(RiskManagement):
         """
         ticket = request[type]
         addtionnal = f", SYMBOL={self.symbol}"
-        result = None 
+        result = None
         try:
             self.check_order(request)
             result = self.send_order(request)
@@ -1839,15 +1828,16 @@ class Trade(RiskManagement):
 
     def sleep_time(self, weekend=False):
         if weekend:
-            # claculate number of minute from the friday and to monday start
-            friday_time = datetime.strptime(self.current_time(), "%H:%M")
+            # calculate number of minute from now and monday start
+            multiplyer = {"friday": 3, "saturday": 2, "sunday": 1}
+            current_time = datetime.strptime(self.current_time(), "%H:%M")
             monday_time = datetime.strptime(self.start, "%H:%M")
-            intra_day_diff = (monday_time - friday_time).total_seconds() // 60
-            inter_day_diff = 3 * 24 * 60
+            intra_day_diff = (monday_time - current_time).total_seconds() // 60
+            inter_day_diff = multiplyer[datetime.now().strftime("%A").lower()] * 24 * 60
             total_minutes = inter_day_diff + intra_day_diff
             return total_minutes
         else:
-            # claculate number of minute from the end to the start
+            # calculate number of minute from the end to the start
             start = datetime.strptime(self.start, "%H:%M")
             end = datetime.strptime(self.current_time(), "%H:%M")
             minutes = (end - start).total_seconds() // 60

bbstrader/metatrader/utils.py

@@ -607,7 +607,8 @@ class AutoTradingDisabled(MT5TerminalError):
 class InternalFailError(MT5TerminalError):
     """Base exception class for internal IPC errors."""
 
-    pass
+    def __init__(self, code, message):
+        super().__init__(code, message)
 
 
 class InternalFailSend(InternalFailError):
@@ -700,9 +701,9 @@ def raise_mt5_error(message: Optional[str] = None):
     """
     if message and isinstance(message, Exception):
         message = str(message)
-    error = _ERROR_CODE_TO_EXCEPTION_.get(MT5.last_error()[0])
-    if error is not None:
-        raise Exception(f"{error(None)} {message or MT5.last_error()[1]}")
+    exception = _ERROR_CODE_TO_EXCEPTION_.get(MT5.last_error()[0])
+    if exception is not None:
+        raise exception(f"{message or MT5.last_error()[1]}")
     else:
         raise Exception(f"{message or MT5.last_error()[1]}")