pdmt5 0.0.7__py3-none-any.whl → 0.0.9__py3-none-any.whl

pdmt5/__init__.py

@@ -4,7 +4,7 @@ from importlib.metadata import version
 
 from .dataframe import Mt5Config, Mt5DataClient
 from .mt5 import Mt5Client, Mt5RuntimeError
-from .trading import Mt5TradingClient
+from .trading import Mt5TradingClient, Mt5TradingError
 
 __version__ = version(__package__) if __package__ else None
 
@@ -14,4 +14,5 @@ __all__ = [
     "Mt5DataClient",
     "Mt5RuntimeError",
     "Mt5TradingClient",
+    "Mt5TradingError",
 ]

pdmt5/dataframe.py

@@ -86,16 +86,16 @@ class Mt5DataClient(Mt5Client):
         for i in range(1 + max(0, self.retry_count)):
             if i:
                 self.logger.warning(
-                    "Retrying MetaTrader5 initialization (%d/%d)...",
+                    "Retrying MT5 initialization (%d/%d)...",
                     i,
                     self.retry_count,
                 )
                 time.sleep(i)
             if self.initialize(**initialize_kwargs):  # type: ignore[reportArgumentType]
-                self.logger.info("MetaTrader5 initialization successful.")
+                self.logger.info("MT5 initialization successful.")
                 return
         error_message = (
-            f"MetaTrader5 initialization failed after {self.retry_count} retries:"
+            f"MT5 initialization failed after {self.retry_count} retries:"
             f" {self.last_error()}"
         )
         raise Mt5RuntimeError(error_message)

pdmt5/mt5.py

@@ -6,12 +6,14 @@ from __future__ import annotations
 
 import importlib
 import logging
+from functools import wraps
 from types import ModuleType  # noqa: TC003
 from typing import TYPE_CHECKING, Any, Self
 
 from pydantic import BaseModel, ConfigDict, Field
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
     from datetime import datetime
     from types import TracebackType
 
@@ -43,6 +45,41 @@ class Mt5Client(BaseModel):
     )
     _is_initialized: bool = False
 
+    @staticmethod
+    def _log_mt5_last_status_code(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Decorator to log MetaTrader5 last status code after method execution.
+
+        Args:
+            func: The method to decorate.
+
+        Returns:
+            The decorated method.
+        """
+
+        @wraps(func)
+        def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            try:
+                response = func(self, *args, **kwargs)
+            except Exception as e:
+                error_message = f"MT5 {func.__name__} failed with error: {e}"
+                raise Mt5RuntimeError(error_message) from e
+            else:
+                self.logger.info(
+                    "MT5 %s returned a response: %s",
+                    func.__name__,
+                    response,
+                )
+                return response
+            finally:
+                last_error_response = self.mt5.last_error()
+                message = f"MT5 last status: {last_error_response}"
+                if last_error_response[0] != self.mt5.RES_S_OK:
+                    self.logger.warning(message)
+                else:
+                    self.logger.info(message)
+
+        return wrapper
+
     def __enter__(self) -> Self:
         """Context manager entry.
 
@@ -61,6 +98,7 @@ class Mt5Client(BaseModel):
         """Context manager exit."""
         self.shutdown()
 
+    @_log_mt5_last_status_code
     def initialize(
         self,
         path: str | None = None,
@@ -83,11 +121,9 @@ class Mt5Client(BaseModel):
         Returns:
             True if successful, False otherwise.
         """
-        if self._is_initialized:
-            self.logger.warning("Skipping initialization, already initialized.")
-        elif path is not None:
+        if path is not None:
             self.logger.info(
-                "Initializing MetaTrader5 connection with path: %s",
+                "Initializing MT5 connection with path: %s",
                 path,
             )
             self._is_initialized = self.mt5.initialize(
@@ -105,10 +141,11 @@ class Mt5Client(BaseModel):
                 },
             )
         else:
-            self.logger.info("Initializing MetaTrader5 connection.")
+            self.logger.info("Initializing MT5 connection.")
             self._is_initialized = self.mt5.initialize()
         return self._is_initialized
 
+    @_log_mt5_last_status_code
     def login(
         self,
         login: int,
@@ -127,8 +164,8 @@ class Mt5Client(BaseModel):
         Returns:
             True if successful, False otherwise.
         """
-        self._ensure_initialized()
-        self.logger.info("Logging in to MetaTrader5 account: %d", login)
+        self._initialize_if_needed()
+        self.logger.info("Logging in to MT5 account: %d", login)
         return self.mt5.login(
             login,
             **{
@@ -142,73 +179,78 @@ class Mt5Client(BaseModel):
             },
         )
 
+    @_log_mt5_last_status_code
     def shutdown(self) -> None:
         """Close the previously established connection to the MetaTrader 5 terminal."""
-        if self._is_initialized:
-            self.logger.info("Shutting down MetaTrader5 connection.")
-            self.mt5.shutdown()
-            self._is_initialized = False
-        else:
-            self.logger.warning(
-                "MetaTrader5 connection is not initialized, nothing to shut down"
-            )
+        self.logger.info("Shutting down MT5 connection.")
+        response = self.mt5.shutdown()
+        self._is_initialized = False
+        return response
 
+    @_log_mt5_last_status_code
     def version(self) -> tuple[int, int, str]:
         """Return the MetaTrader 5 terminal version.
 
         Returns:
             Tuple of (terminal_version, build, release_date).
         """
-        self._ensure_initialized()
-        self.logger.info("Retrieving MetaTrader5 version information.")
+        self._initialize_if_needed()
+        self.logger.info("Retrieving MT5 version information.")
         return self.mt5.version()
 
+    @_log_mt5_last_status_code
     def last_error(self) -> tuple[int, str]:
         """Return data on the last error.
 
         Returns:
             Tuple of (error_code, error_description).
         """
-        self.logger.info("Retrieving last MetaTrader5 error")
+        self.logger.info("Retrieving last MT5 error")
         return self.mt5.last_error()
 
+    @_log_mt5_last_status_code
     def account_info(self) -> Any:
         """Get info on the current trading account.
 
         Returns:
             AccountInfo structure or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Retrieving account information.")
         response = self.mt5.account_info()
-        self._validate_metatrader5_response(response=response, operation="account_info")
+        self._validate_mt5_response_is_not_none(
+            response=response, operation="account_info"
+        )
         return response
 
+    @_log_mt5_last_status_code
     def terminal_info(self) -> Any:
         """Get the connected MetaTrader 5 client terminal status and settings.
 
         Returns:
             TerminalInfo structure or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Retrieving terminal information.")
         response = self.mt5.terminal_info()
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="terminal_info",
         )
         return response
 
+    @_log_mt5_last_status_code
     def symbols_total(self) -> int:
         """Get the number of all financial instruments in the terminal.
 
         Returns:
             Total number of symbols.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Retrieving total number of symbols.")
         return self.mt5.symbols_total()
 
+    @_log_mt5_last_status_code
     def symbols_get(self, group: str | None = None) -> tuple[Any, ...]:
         """Get all financial instruments from the terminal.
 
@@ -218,7 +260,7 @@ class Mt5Client(BaseModel):
         Returns:
             Tuple of symbol info structures or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         if group is not None:
             self.logger.info("Retrieving symbols for group: %s", group)
             response = self.mt5.symbols_get(group=group)
@@ -227,13 +269,14 @@ class Mt5Client(BaseModel):
             self.logger.info("Retrieving all symbols.")
             response = self.mt5.symbols_get()
             context = None
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="symbols_get",
             context=context,
         )
         return response
 
+    @_log_mt5_last_status_code
     def symbol_info(self, symbol: str) -> Any:
         """Get data on the specified financial instrument.
 
@@ -243,16 +286,17 @@ class Mt5Client(BaseModel):
         Returns:
             Symbol info structure or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Retrieving information for symbol: %s", symbol)
         response = self.mt5.symbol_info(symbol)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="symbol_info",
             context=f"symbol={symbol}",
         )
         return response
 
+    @_log_mt5_last_status_code
     def symbol_info_tick(self, symbol: str) -> Any:
         """Get the last tick for the specified financial instrument.
 
@@ -262,16 +306,17 @@ class Mt5Client(BaseModel):
         Returns:
             Tick info structure or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Retrieving last tick for symbol: %s", symbol)
         response = self.mt5.symbol_info_tick(symbol)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="symbol_info_tick",
             context=f"symbol={symbol}",
         )
         return response
 
+    @_log_mt5_last_status_code
     def symbol_select(self, symbol: str, enable: bool = True) -> bool:
         """Select a symbol in the MarketWatch window or remove a symbol from the window.
 
@@ -282,16 +327,17 @@ class Mt5Client(BaseModel):
         Returns:
             True if successful, False otherwise.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Selecting symbol: %s, enable=%s", symbol, enable)
         response = self.mt5.symbol_select(symbol, enable)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="symbol_select",
             context=f"symbol={symbol}, enable={enable}",
         )
         return response
 
+    @_log_mt5_last_status_code
     def market_book_add(self, symbol: str) -> bool:
         """Subscribe the terminal to the Market Depth change events for a specified symbol.
 
@@ -301,16 +347,17 @@ class Mt5Client(BaseModel):
         Returns:
             True if successful, False otherwise.
         """  # noqa: E501
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Adding market book for symbol: %s", symbol)
         response = self.mt5.market_book_add(symbol)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="market_book_add",
             context=f"symbol={symbol}",
         )
         return response
 
+    @_log_mt5_last_status_code
     def market_book_get(self, symbol: str) -> tuple[Any, ...]:
         """Return a tuple from BookInfo featuring Market Depth entries for the specified symbol.
 
@@ -320,16 +367,17 @@ class Mt5Client(BaseModel):
         Returns:
             Tuple of BookInfo structures or None.
         """  # noqa: E501
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Retrieving market book for symbol: %s", symbol)
         response = self.mt5.market_book_get(symbol)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="market_book_get",
             context=f"symbol={symbol}",
         )
         return response
 
+    @_log_mt5_last_status_code
     def market_book_release(self, symbol: str) -> bool:
         """Cancels subscription of the terminal to the Market Depth change events for a specified symbol.
 
@@ -339,16 +387,17 @@ class Mt5Client(BaseModel):
         Returns:
             True if successful, False otherwise.
         """  # noqa: E501
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Releasing market book for symbol: %s", symbol)
         response = self.mt5.market_book_release(symbol)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="market_book_release",
             context=f"symbol={symbol}",
         )
         return response
 
+    @_log_mt5_last_status_code
     def copy_rates_from(
         self,
         symbol: str,
@@ -367,7 +416,7 @@ class Mt5Client(BaseModel):
         Returns:
             Array of rates or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info(
             "Copying rates from symbol: %s, timeframe: %d, date_from: %s, count: %d",
             symbol,
@@ -376,7 +425,7 @@ class Mt5Client(BaseModel):
             count,
         )
         response = self.mt5.copy_rates_from(symbol, timeframe, date_from, count)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="copy_rates_from",
             context=(
@@ -386,6 +435,7 @@ class Mt5Client(BaseModel):
         )
         return response
 
+    @_log_mt5_last_status_code
     def copy_rates_from_pos(
         self,
         symbol: str,
@@ -404,7 +454,7 @@ class Mt5Client(BaseModel):
         Returns:
             Array of rates or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info(
             (
                 "Copying rates from position:"
@@ -416,7 +466,7 @@ class Mt5Client(BaseModel):
             count,
         )
         response = self.mt5.copy_rates_from_pos(symbol, timeframe, start_pos, count)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="copy_rates_from_pos",
             context=(
@@ -426,6 +476,7 @@ class Mt5Client(BaseModel):
         )
         return response
 
+    @_log_mt5_last_status_code
     def copy_rates_range(
         self,
         symbol: str,
@@ -444,7 +495,7 @@ class Mt5Client(BaseModel):
         Returns:
             Array of rates or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info(
             "Copying rates range: symbol=%s, timeframe=%d, date_from=%s, date_to=%s",
             symbol,
@@ -453,7 +504,7 @@ class Mt5Client(BaseModel):
             date_to,
         )
         response = self.mt5.copy_rates_range(symbol, timeframe, date_from, date_to)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="copy_rates_range",
             context=(
@@ -463,6 +514,7 @@ class Mt5Client(BaseModel):
         )
         return response
 
+    @_log_mt5_last_status_code
     def copy_ticks_from(
         self,
         symbol: str,
@@ -481,7 +533,7 @@ class Mt5Client(BaseModel):
         Returns:
             Array of ticks or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info(
             "Copying ticks from symbol: %s, date_from: %s, count: %d, flags: %d",
             symbol,
@@ -490,7 +542,7 @@ class Mt5Client(BaseModel):
             flags,
         )
         response = self.mt5.copy_ticks_from(symbol, date_from, count, flags)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="copy_ticks_from",
             context=(
@@ -499,6 +551,7 @@ class Mt5Client(BaseModel):
         )
         return response
 
+    @_log_mt5_last_status_code
     def copy_ticks_range(
         self,
         symbol: str,
@@ -517,7 +570,7 @@ class Mt5Client(BaseModel):
         Returns:
             Array of ticks or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info(
             "Copying ticks range: symbol=%s, date_from=%s, date_to=%s, flags=%d",
             symbol,
@@ -526,7 +579,7 @@ class Mt5Client(BaseModel):
             flags,
         )
         response = self.mt5.copy_ticks_range(symbol, date_from, date_to, flags)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="copy_ticks_range",
             context=(
@@ -536,16 +589,18 @@ class Mt5Client(BaseModel):
         )
         return response
 
+    @_log_mt5_last_status_code
     def orders_total(self) -> int:
         """Get the number of active orders.
 
         Returns:
             Number of active orders.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Retrieving total number of active orders.")
         return self.mt5.orders_total()
 
+    @_log_mt5_last_status_code
     def orders_get(
         self,
         symbol: str | None = None,
@@ -562,7 +617,7 @@ class Mt5Client(BaseModel):
         Returns:
             Tuple of order info structures or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         if ticket is not None:
             self.logger.info("Retrieving order with ticket: %d", ticket)
             response = self.mt5.orders_get(ticket=ticket)
@@ -579,13 +634,14 @@ class Mt5Client(BaseModel):
             self.logger.info("Retrieving all active orders.")
             response = self.mt5.orders_get()
             context = None
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="orders_get",
             context=context,
         )
         return response
 
+    @_log_mt5_last_status_code
     def order_calc_margin(
         self,
         action: int,
@@ -604,7 +660,7 @@ class Mt5Client(BaseModel):
         Returns:
             Required margin amount or None.
         """  # noqa: E501
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info(
             "Calculating margin: action=%d, symbol=%s, volume=%.2f, price=%.5f",
             action,
@@ -613,13 +669,14 @@ class Mt5Client(BaseModel):
             price,
         )
         response = self.mt5.order_calc_margin(action, symbol, volume, price)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="order_calc_margin",
             context=f"action={action}, symbol={symbol}, volume={volume}, price={price}",
         )
         return response
 
+    @_log_mt5_last_status_code
     def order_calc_profit(
         self,
         action: int,
@@ -640,7 +697,7 @@ class Mt5Client(BaseModel):
         Returns:
             Calculated profit or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info(
             (
                 "Calculating profit: action=%d, symbol=%s, volume=%.2f,"
@@ -655,7 +712,7 @@ class Mt5Client(BaseModel):
         response = self.mt5.order_calc_profit(
             action, symbol, volume, price_open, price_close
         )
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="order_calc_profit",
             context=(
@@ -665,6 +722,7 @@ class Mt5Client(BaseModel):
         )
         return response
 
+    @_log_mt5_last_status_code
     def order_check(self, request: dict[str, Any]) -> Any:
         """Check funds sufficiency for performing a required trading operation.
 
@@ -674,16 +732,17 @@ class Mt5Client(BaseModel):
         Returns:
             OrderCheckResult structure or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Checking order with request: %s", request)
         response = self.mt5.order_check(request)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="order_check",
             context=f"request={request}",
         )
         return response
 
+    @_log_mt5_last_status_code
     def order_send(self, request: dict[str, Any]) -> Any:
         """Send a request to perform a trading operation from the terminal to the trade server.
 
@@ -693,26 +752,28 @@ class Mt5Client(BaseModel):
         Returns:
             OrderSendResult structure or None.
         """  # noqa: E501
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Sending order with request: %s", request)
         response = self.mt5.order_send(request)
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="order_send",
             context=f"request={request}",
         )
         return response
 
+    @_log_mt5_last_status_code
     def positions_total(self) -> int:
         """Get the number of open positions.
 
         Returns:
             Number of open positions.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info("Retrieving total number of open positions.")
         return self.mt5.positions_total()
 
+    @_log_mt5_last_status_code
     def positions_get(
         self,
         symbol: str | None = None,
@@ -729,7 +790,7 @@ class Mt5Client(BaseModel):
         Returns:
             Tuple of position info structures or None.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         if ticket is not None:
             self.logger.info("Retrieving position with ticket: %d", ticket)
             response = self.mt5.positions_get(ticket=ticket)
@@ -746,13 +807,14 @@ class Mt5Client(BaseModel):
             self.logger.info("Retrieving all open positions.")
             response = self.mt5.positions_get()
             context = None
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="positions_get",
             context=context,
         )
         return response
 
+    @_log_mt5_last_status_code
     def history_orders_total(
         self,
         date_from: datetime | int,
@@ -767,7 +829,7 @@ class Mt5Client(BaseModel):
         Returns:
             Number of historical orders.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info(
             "Retrieving total number of historical orders from %s to %s",
             date_from,
@@ -775,6 +837,7 @@ class Mt5Client(BaseModel):
         )
         return self.mt5.history_orders_total(date_from, date_to)
 
+    @_log_mt5_last_status_code
     def history_orders_get(
         self,
         date_from: datetime | int | None = None,
@@ -795,7 +858,7 @@ class Mt5Client(BaseModel):
         Returns:
             Tuple of historical order info structures or None.
         """  # noqa: E501
-        self._ensure_initialized()
+        self._initialize_if_needed()
         if ticket is not None:
             self.logger.info("Retrieving order with ticket: %d", ticket)
             response = self.mt5.history_orders_get(ticket=ticket)
@@ -821,13 +884,14 @@ class Mt5Client(BaseModel):
             )
             response = self.mt5.history_orders_get(date_from, date_to)
             context = f"date_from={date_from}, date_to={date_to}"
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="history_orders_get",
             context=context,
         )
         return response
 
+    @_log_mt5_last_status_code
     def history_deals_total(
         self,
         date_from: datetime | int,
@@ -842,7 +906,7 @@ class Mt5Client(BaseModel):
         Returns:
             Number of historical deals.
         """
-        self._ensure_initialized()
+        self._initialize_if_needed()
         self.logger.info(
             "Retrieving total number of historical deals from %s to %s",
             date_from,
@@ -850,6 +914,7 @@ class Mt5Client(BaseModel):
         )
         return self.mt5.history_deals_total(date_from, date_to)
 
+    @_log_mt5_last_status_code
     def history_deals_get(
         self,
         date_from: datetime | int | None = None,
@@ -870,7 +935,7 @@ class Mt5Client(BaseModel):
         Returns:
             Tuple of historical deal info structures or None.
         """  # noqa: E501
-        self._ensure_initialized()
+        self._initialize_if_needed()
         if ticket is not None:
             self.logger.info("Retrieving deal with ticket: %d", ticket)
             response = self.mt5.history_deals_get(ticket=ticket)
@@ -896,20 +961,25 @@ class Mt5Client(BaseModel):
             )
             response = self.mt5.history_deals_get(date_from, date_to)
             context = f"date_from={date_from}, date_to={date_to}"
-        self._validate_metatrader5_response(
+        self._validate_mt5_response_is_not_none(
             response=response,
             operation="history_deals_get",
             context=context,
         )
         return response
 
-    def _validate_metatrader5_response(
+    def _initialize_if_needed(self) -> None:
+        """Ensure the MetaTrader5 client is initialized before performing operations."""
+        if not self._is_initialized:
+            self.initialize()
+
+    def _validate_mt5_response_is_not_none(
         self,
         response: Any,
         operation: str,
         context: str | None = None,
     ) -> None:
-        """Validate the response from MetaTrader5 terminal functions.
+        """Validate that the MetaTrader5 response is not None.
 
         Args:
             response: The response object to validate.
@@ -920,20 +990,8 @@ class Mt5Client(BaseModel):
             Mt5RuntimeError: With error details from MetaTrader5.
         """
         if response is None:
-            error_code, error_description = self.last_error()
             error_message = (
-                f"{operation} failed: {error_code} - {error_description}"
-                + (f" (context: {context})" if context else "")
-            )
-            self.logger.error(error_message)
-            raise Mt5RuntimeError(error_message)
-
-    def _ensure_initialized(self) -> None:
-        """Ensure MetaTrader5 is initialized.
-
-        Raises:
-            Mt5RuntimeError: If MetaTrader5 is not initialized.
-        """
-        if not self._is_initialized:
-            error_message = "MetaTrader5 not initialized. Call initialize() first."
+                f"MT5 {operation} returned {response}:"
+                f" last_error={self.mt5.last_error()}"
+            ) + (f" context={context}" if context else "")
             raise Mt5RuntimeError(error_message)

pdmt5/trading.py

@@ -31,7 +31,7 @@ class Mt5TradingClient(Mt5DataClient):
 
     def close_open_positions(
         self,
-        symbols: str | list[str] | tuple[str] | None = None,
+        symbols: str | list[str] | tuple[str, ...] | None = None,
         **kwargs: Any,  # noqa: ANN401
     ) -> dict[str, list[dict[str, Any]]]:
         """Close all open positions for specified symbols.
@@ -51,6 +51,7 @@ class Mt5TradingClient(Mt5DataClient):
             symbol_list = symbols
         else:
             symbol_list = self.symbols_get()
+        self.logger.info("Fetching and closing positions for symbols: %s", symbol_list)
         return {
             s: self._fetch_and_close_position(symbol=s, **kwargs) for s in symbol_list
         }
@@ -99,11 +100,17 @@ class Mt5TradingClient(Mt5DataClient):
                 for p in positions_dict
             ]
 
-    def send_or_check_order(self, request: dict[str, Any]) -> dict[str, Any]:
+    def send_or_check_order(
+        self,
+        request: dict[str, Any],
+        dry_run: bool | None = None,
+    ) -> dict[str, Any]:
         """Send or check an order request.
 
         Args:
             request: Order request dictionary.
+            dry_run: Optional flag to enable dry run mode. If None, uses the instance's
+                `dry_run` attribute.
 
         Returns:
             Dictionary with operation result.
@@ -112,29 +119,66 @@ class Mt5TradingClient(Mt5DataClient):
             Mt5TradingError: If the order operation fails.
         """
         self.logger.debug("request: %s", request)
-        if self.dry_run:
+        is_dry_run = dry_run if dry_run is not None else self.dry_run
+        self.logger.debug("is_dry_run: %s", is_dry_run)
+        if is_dry_run:
             response = self.order_check_as_dict(request=request)
             order_func = "order_check"
         else:
             response = self.order_send_as_dict(request=request)
             order_func = "order_send"
         retcode = response.get("retcode")
-        if ((not self.dry_run) and retcode == self.mt5.TRADE_RETCODE_DONE) or (
-            self.dry_run and retcode == 0
+        if ((not is_dry_run) and retcode == self.mt5.TRADE_RETCODE_DONE) or (
+            is_dry_run and retcode == 0
         ):
-            self.logger.info("retcode: %s, response: %s", retcode, response)
+            self.logger.info("response: %s", response)
             return response
         elif retcode in {
             self.mt5.TRADE_RETCODE_TRADE_DISABLED,
             self.mt5.TRADE_RETCODE_MARKET_CLOSED,
         }:
-            self.logger.info("retcode: %s, response: %s", retcode, response)
+            self.logger.info("response: %s", response)
             comment = response.get("comment", "Unknown error")
             self.logger.warning("%s() failed and skipped. <= `%s`", order_func, comment)
             return response
         else:
-            self.logger.error("retcode: %s, response: %s", retcode, response)
+            self.logger.error("response: %s", response)
             comment = response.get("comment", "Unknown error")
             error_message = f"{order_func}() failed and aborted. <= `{comment}`"
-            self.logger.error(error_message)
+            raise Mt5TradingError(error_message)
+
+    def calculate_minimum_order_margins(self, symbol: str) -> dict[str, float]:
+        """Calculate minimum order margins for a given symbol.
+
+        Args:
+            symbol: Symbol for which to calculate minimum order margins.
+
+        Returns:
+            Dictionary with margin information.
+
+        Raises:
+            Mt5TradingError: If margin calculation fails.
+        """
+        symbol_info = self.symbol_info_as_dict(symbol=symbol)
+        symbol_info_tick = self.symbol_info_tick_as_dict(symbol=symbol)
+        min_ask_order_margin = self.mt5.order_calc_margin(
+            action=self.mt5.ORDER_TYPE_BUY,
+            symbol=symbol,
+            volume=symbol_info["volume_min"],
+            price=symbol_info_tick["ask"],
+        )
+        min_bid_order_margin = self.mt5.order_calc_margin(
+            action=self.mt5.ORDER_TYPE_SELL,
+            symbol=symbol,
+            volume=symbol_info["volume_min"],
+            price=symbol_info_tick["bid"],
+        )
+        min_order_margins = {"ask": min_ask_order_margin, "bid": min_bid_order_margin}
+        self.logger.info("Minimum order margins for %s: %s", symbol, min_order_margins)
+        if all(min_order_margins.values()):
+            return min_order_margins
+        else:
+            error_message = (
+                f"Failed to calculate minimum order margins for symbol: {symbol}."
+            )
             raise Mt5TradingError(error_message)

{pdmt5-0.0.7.dist-info → pdmt5-0.0.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdmt5
-Version: 0.0.7
+Version: 0.0.9
 Summary: Pandas-based data handler for MetaTrader 5
 Project-URL: Repository, https://github.com/dceoy/pdmt5.git
 Author-email: dceoy <dceoy@users.noreply.github.com>

pdmt5-0.0.9.dist-info/RECORD

@@ -0,0 +1,9 @@
+pdmt5/__init__.py,sha256=QbSFrsi7_bgFzb-ma4DmmUjR90UvrqKMnRZq1wPRmoI,446
+pdmt5/dataframe.py,sha256=MumdFp72ZN_394X_viMkovfyb1c8C-LxLFTdymLEMYM,38345
+pdmt5/mt5.py,sha256=rAY7MQalobUWZtMfC_xyTFCDTuU3EkFAyY_geBl6cyg,32379
+pdmt5/trading.py,sha256=NCrZZuPC1AoUQ_Rmv3_g39VbMxq7R1wASQa5oAMBKDQ,6995
+pdmt5/utils.py,sha256=Ll5Q3OE5h1A_sZ_qVEnOPGniFlT6_MmHfuu0zqeLdeU,3913
+pdmt5-0.0.9.dist-info/METADATA,sha256=Dpc0ApxD4EK_E1Bggyv2vexqIVr4JnfuCglERHHuy8s,9029
+pdmt5-0.0.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pdmt5-0.0.9.dist-info/licenses/LICENSE,sha256=iABrdaUGOBWLYotFupB_PGe8arV5o7rVhn-_vK6P704,1073
+pdmt5-0.0.9.dist-info/RECORD,,

pdmt5-0.0.7.dist-info/RECORD

@@ -1,9 +0,0 @@
-pdmt5/__init__.py,sha256=mJ1gMqZ_MKYZ-53N41MvkwNdPhfcpq15NczCz74fD7w,406
-pdmt5/dataframe.py,sha256=808kwi_eUlpXvgvJzXxwDTvxp80z-1zh605ONyOIoU4,38369
-pdmt5/mt5.py,sha256=vZMIz7h7KWDegX23KEIryby-WC5hJ4wN7pp-FMTdeZ8,30498
-pdmt5/trading.py,sha256=8JagrLc9cjr9TUdkoRmyAmVUOV2SQElqsrtcwg5FqBs,5284
-pdmt5/utils.py,sha256=Ll5Q3OE5h1A_sZ_qVEnOPGniFlT6_MmHfuu0zqeLdeU,3913
-pdmt5-0.0.7.dist-info/METADATA,sha256=w0kr0tob2G_h-u9DuVifML9Q5BIyVY5tHUD1YKyyLjk,9029
-pdmt5-0.0.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pdmt5-0.0.7.dist-info/licenses/LICENSE,sha256=iABrdaUGOBWLYotFupB_PGe8arV5o7rVhn-_vK6P704,1073
-pdmt5-0.0.7.dist-info/RECORD,,