pdmt5 0.1.5__tar.gz → 0.1.6__tar.gz

{pdmt5-0.1.5 → pdmt5-0.1.6}/.github/workflows/ci.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
       - name: Set up uv
-        uses: astral-sh/setup-uv@7edac99f961f18b581bbd960d59d049f04c0002f  # v6.4.1
+        uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc  # v6.4.3
       - name: Install the package
         run: >
           uv sync

{pdmt5-0.1.5 → pdmt5-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdmt5
-Version: 0.1.5
+Version: 0.1.6
 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>
@@ -42,6 +42,8 @@ Pandas-based data handler for MetaTrader 5
 - 🚀 **Context Manager Support**: Clean initialization and cleanup with `with` statements
 - 📈 **Time Series Ready**: OHLCV data with proper datetime indexing
 - 🛡️ **Robust Error Handling**: Custom exceptions with detailed MT5 error information
+- 💰 **Advanced Trading Operations**: Position management, margin calculations, and risk analysis tools
+- 🧪 **Dry Run Mode**: Test trading strategies without executing real trades
 
 ## Requirements
 
@@ -195,9 +197,10 @@ Advanced trading operations client that extends Mt5DataClient:
 - **Position Management**:
   - `close_open_positions()` - Close all positions for specified symbol(s)
   - `place_market_order()` - Place market orders with configurable side, volume, and execution modes
-  - `update_open_position_sltp()` - Modify stop loss and take profit levels for open positions
-- **Market Analysis**:
-  - `calculate_minimum_order_margins()` - Calculate minimum required margins for buy/sell orders
+  - `update_sltp_for_open_positions()` - Modify stop loss and take profit levels for open positions
+- **Margin Calculations**:
+  - `calculate_minimum_order_margin()` - Calculate minimum required margin for a specific order side
+  - `calculate_volume_by_margin()` - Calculate maximum volume for given margin amount
   - `calculate_spread_ratio()` - Calculate normalized bid-ask spread ratio
   - `calculate_new_position_margin_ratio()` - Calculate margin ratio for potential new positions
 - **Simplified Data Access**:
@@ -299,22 +302,20 @@ with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
     )
     print(f"Order placed: {order_result['retcode']}")
 
-    # Update stop loss and take profit for an open position
-    if positions := trader.positions_get_as_df(symbol="EURUSD"):
-        position_ticket = positions.iloc[0]['ticket']
-        update_result = trader.update_open_position_sltp(
-            symbol="EURUSD",
-            position_ticket=position_ticket,
-            sl=1.0950,  # New stop loss
-            tp=1.1050   # New take profit
-        )
-        print(f"Position updated: {update_result['retcode']}")
+    # Update stop loss and take profit for open positions
+    update_results = trader.update_sltp_for_open_positions(
+        symbol="EURUSD",
+        stop_loss=1.0950,   # New stop loss
+        take_profit=1.1050  # New take profit
+    )
+    for result in update_results:
+        print(f"Position updated: {result['retcode']}")
 
     # Calculate margin ratio for a new position
     margin_ratio = trader.calculate_new_position_margin_ratio(
         symbol="EURUSD",
-        new_side="SELL",
-        new_volume=0.2
+        new_position_side="SELL",
+        new_position_volume=0.2
     )
     print(f"New position margin ratio: {margin_ratio:.2%}")
 
@@ -347,10 +348,18 @@ with Mt5TradingClient(config=config) as trader:
     spread_ratio = trader.calculate_spread_ratio("EURUSD")
     print(f"EURUSD spread ratio: {spread_ratio:.5f}")
 
-    # Get minimum order margins
-    margins = trader.calculate_minimum_order_margins("EURUSD")
-    print(f"Minimum ask margin: {margins['ask']}")
-    print(f"Minimum bid margin: {margins['bid']}")
+    # Get minimum order margin for BUY and SELL
+    buy_margin = trader.calculate_minimum_order_margin("EURUSD", "BUY")
+    sell_margin = trader.calculate_minimum_order_margin("EURUSD", "SELL")
+    print(f"Minimum BUY margin: {buy_margin['margin']} (volume: {buy_margin['volume']})")
+    print(f"Minimum SELL margin: {sell_margin['margin']} (volume: {sell_margin['volume']})")
+    
+    # Calculate volume by margin
+    available_margin = 1000.0
+    max_buy_volume = trader.calculate_volume_by_margin("EURUSD", available_margin, "BUY")
+    max_sell_volume = trader.calculate_volume_by_margin("EURUSD", available_margin, "SELL")
+    print(f"Max BUY volume for ${available_margin}: {max_buy_volume}")
+    print(f"Max SELL volume for ${available_margin}: {max_sell_volume}")
 
     # Get recent OHLC data with custom timeframe
     rates_df = trader.fetch_latest_rates_as_df(

{pdmt5-0.1.5 → pdmt5-0.1.6}/README.md

@@ -19,6 +19,8 @@ Pandas-based data handler for MetaTrader 5
 - 🚀 **Context Manager Support**: Clean initialization and cleanup with `with` statements
 - 📈 **Time Series Ready**: OHLCV data with proper datetime indexing
 - 🛡️ **Robust Error Handling**: Custom exceptions with detailed MT5 error information
+- 💰 **Advanced Trading Operations**: Position management, margin calculations, and risk analysis tools
+- 🧪 **Dry Run Mode**: Test trading strategies without executing real trades
 
 ## Requirements
 
@@ -172,9 +174,10 @@ Advanced trading operations client that extends Mt5DataClient:
 - **Position Management**:
   - `close_open_positions()` - Close all positions for specified symbol(s)
   - `place_market_order()` - Place market orders with configurable side, volume, and execution modes
-  - `update_open_position_sltp()` - Modify stop loss and take profit levels for open positions
-- **Market Analysis**:
-  - `calculate_minimum_order_margins()` - Calculate minimum required margins for buy/sell orders
+  - `update_sltp_for_open_positions()` - Modify stop loss and take profit levels for open positions
+- **Margin Calculations**:
+  - `calculate_minimum_order_margin()` - Calculate minimum required margin for a specific order side
+  - `calculate_volume_by_margin()` - Calculate maximum volume for given margin amount
   - `calculate_spread_ratio()` - Calculate normalized bid-ask spread ratio
   - `calculate_new_position_margin_ratio()` - Calculate margin ratio for potential new positions
 - **Simplified Data Access**:
@@ -276,22 +279,20 @@ with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
     )
     print(f"Order placed: {order_result['retcode']}")
 
-    # Update stop loss and take profit for an open position
-    if positions := trader.positions_get_as_df(symbol="EURUSD"):
-        position_ticket = positions.iloc[0]['ticket']
-        update_result = trader.update_open_position_sltp(
-            symbol="EURUSD",
-            position_ticket=position_ticket,
-            sl=1.0950,  # New stop loss
-            tp=1.1050   # New take profit
-        )
-        print(f"Position updated: {update_result['retcode']}")
+    # Update stop loss and take profit for open positions
+    update_results = trader.update_sltp_for_open_positions(
+        symbol="EURUSD",
+        stop_loss=1.0950,   # New stop loss
+        take_profit=1.1050  # New take profit
+    )
+    for result in update_results:
+        print(f"Position updated: {result['retcode']}")
 
     # Calculate margin ratio for a new position
     margin_ratio = trader.calculate_new_position_margin_ratio(
         symbol="EURUSD",
-        new_side="SELL",
-        new_volume=0.2
+        new_position_side="SELL",
+        new_position_volume=0.2
     )
     print(f"New position margin ratio: {margin_ratio:.2%}")
 
@@ -324,10 +325,18 @@ with Mt5TradingClient(config=config) as trader:
     spread_ratio = trader.calculate_spread_ratio("EURUSD")
     print(f"EURUSD spread ratio: {spread_ratio:.5f}")
 
-    # Get minimum order margins
-    margins = trader.calculate_minimum_order_margins("EURUSD")
-    print(f"Minimum ask margin: {margins['ask']}")
-    print(f"Minimum bid margin: {margins['bid']}")
+    # Get minimum order margin for BUY and SELL
+    buy_margin = trader.calculate_minimum_order_margin("EURUSD", "BUY")
+    sell_margin = trader.calculate_minimum_order_margin("EURUSD", "SELL")
+    print(f"Minimum BUY margin: {buy_margin['margin']} (volume: {buy_margin['volume']})")
+    print(f"Minimum SELL margin: {sell_margin['margin']} (volume: {sell_margin['volume']})")
+    
+    # Calculate volume by margin
+    available_margin = 1000.0
+    max_buy_volume = trader.calculate_volume_by_margin("EURUSD", available_margin, "BUY")
+    max_sell_volume = trader.calculate_volume_by_margin("EURUSD", available_margin, "SELL")
+    print(f"Max BUY volume for ${available_margin}: {max_buy_volume}")
+    print(f"Max SELL volume for ${available_margin}: {max_sell_volume}")
 
     # Get recent OHLC data with custom timeframe
     rates_df = trader.fetch_latest_rates_as_df(

{pdmt5-0.1.5 → pdmt5-0.1.6}/docs/api/trading.md

@@ -47,7 +47,7 @@ with client:
     # Get current positions as DataFrame
     positions_df = client.get_positions_as_df()
     print(f"Open positions: {len(positions_df)}")
-    
+
     # Close positions for specific symbol
     results = client.close_open_positions("EURUSD")
     print(f"Closed positions: {results}")
@@ -62,7 +62,7 @@ client = Mt5TradingClient(config=config, dry_run=False)
 with client:
     # Close all positions for multiple symbols
     results = client.close_open_positions(["EURUSD", "GBPUSD", "USDJPY"])
-    
+
     # Close all positions (all symbols)
     all_results = client.close_open_positions()
 ```
@@ -73,19 +73,19 @@ with client:
 # Configure different order filling modes
 # IOC (Immediate or Cancel) - default
 client_ioc = Mt5TradingClient(
-    config=config, 
+    config=config,
     order_filling_mode="IOC"
 )
 
 # FOK (Fill or Kill)
 client_fok = Mt5TradingClient(
-    config=config, 
+    config=config,
     order_filling_mode="FOK"
 )
 
 # RETURN (Return if not filled)
 client_return = Mt5TradingClient(
-    config=config, 
+    config=config,
     order_filling_mode="RETURN"
 )
 ```
@@ -121,7 +121,7 @@ except Mt5TradingError as e:
 with client:
     # Check order (note: send_or_check_order is an internal method)
     # For trading operations, use the provided methods like close_open_positions
-    
+
     # Example: Check if we can close a position
     positions = client.get_positions_as_df()
     if not positions.empty:
@@ -196,6 +196,173 @@ The `close_open_positions()` method returns a dictionary with symbols as keys:
 - `TRADE_RETCODE_NO_MONEY`: Insufficient funds
 - `TRADE_RETCODE_INVALID_VOLUME`: Invalid trade volume
 
+## Margin Calculation Methods
+
+The trading client provides advanced margin calculation capabilities:
+
+### Calculate Minimum Order Margin
+
+```python
+with client:
+    # Calculate minimum margin required for BUY order
+    min_margin_buy = client.calculate_minimum_order_margin("EURUSD", "BUY")
+    print(f"Minimum volume: {min_margin_buy['volume']}")
+    print(f"Minimum margin: {min_margin_buy['margin']}")
+
+    # Calculate minimum margin required for SELL order
+    min_margin_sell = client.calculate_minimum_order_margin("EURUSD", "SELL")
+```
+
+### Calculate Volume by Margin
+
+```python
+with client:
+    # Calculate maximum volume for given margin amount
+    available_margin = 1000.0  # USD
+    max_volume_buy = client.calculate_volume_by_margin("EURUSD", available_margin, "BUY")
+    max_volume_sell = client.calculate_volume_by_margin("EURUSD", available_margin, "SELL")
+
+    print(f"Max BUY volume for ${available_margin}: {max_volume_buy}")
+    print(f"Max SELL volume for ${available_margin}: {max_volume_sell}")
+```
+
+### Calculate New Position Margin Ratio
+
+```python
+with client:
+    # Calculate margin ratio for potential new position
+    margin_ratio = client.calculate_new_position_margin_ratio(
+        symbol="EURUSD",
+        new_position_side="BUY",
+        new_position_volume=1.0
+    )
+    print(f"New position would use {margin_ratio:.2%} of account equity")
+
+    # Check if adding position would exceed risk limits
+    if margin_ratio > 0.1:  # 10% risk limit
+        print("Position size too large for risk management")
+```
+
+## Market Order Placement
+
+Place market orders with flexible configuration:
+
+```python
+with client:
+    # Place a BUY market order
+    result = client.place_market_order(
+        symbol="EURUSD",
+        volume=1.0,
+        order_side="BUY",
+        order_filling_mode="IOC",  # Immediate or Cancel
+        order_time_mode="GTC",     # Good Till Cancelled
+        dry_run=False,             # Set to True for testing
+        comment="My buy order"
+    )
+
+    # Place a SELL market order with FOK filling
+    result = client.place_market_order(
+        symbol="EURUSD",
+        volume=0.5,
+        order_side="SELL",
+        order_filling_mode="FOK",  # Fill or Kill
+        dry_run=True  # Test mode
+    )
+
+    print(f"Order result: {result}")
+```
+
+## Stop Loss and Take Profit Management
+
+Update SL/TP for existing positions:
+
+```python
+with client:
+    # Update SL/TP for all EURUSD positions
+    results = client.update_sltp_for_open_positions(
+        symbol="EURUSD",
+        stop_loss=1.0950,
+        take_profit=1.1100,
+        dry_run=False
+    )
+
+    # Update only specific positions by ticket
+    results = client.update_sltp_for_open_positions(
+        symbol="EURUSD",
+        stop_loss=1.0950,
+        tickets=[123456, 789012],  # Specific position tickets
+        dry_run=True
+    )
+```
+
+## Market Data and Analysis Methods
+
+### Spread Analysis
+
+```python
+with client:
+    # Calculate spread ratio for symbol
+    spread_ratio = client.calculate_spread_ratio("EURUSD")
+    print(f"EURUSD spread ratio: {spread_ratio:.6f}")
+```
+
+### OHLC Data Retrieval
+
+```python
+with client:
+    # Fetch latest rate data as DataFrame
+    rates_df = client.fetch_latest_rates_as_df(
+        symbol="EURUSD",
+        granularity="M1",  # 1-minute bars
+        count=1440,        # Last 24 hours
+        index_keys="time"
+    )
+    print(f"Latest rates: {rates_df.tail()}")
+```
+
+### Tick Data Analysis
+
+```python
+with client:
+    # Fetch recent tick data
+    ticks_df = client.fetch_latest_ticks_as_df(
+        symbol="EURUSD",
+        seconds=300,           # Last 5 minutes
+        index_keys="time_msc"
+    )
+    print(f"Tick count: {len(ticks_df)}")
+```
+
+### Position Analytics with Enhanced Metrics
+
+```python
+with client:
+    # Get positions with additional calculated metrics
+    positions_df = client.fetch_positions_with_metrics_as_df("EURUSD")
+
+    if not positions_df.empty:
+        print("Position metrics:")
+        print(f"Total signed volume: {positions_df['signed_volume'].sum()}")
+        print(f"Total signed margin: {positions_df['signed_margin'].sum()}")
+        print(f"Average profit ratio: {positions_df['underlier_profit_ratio'].mean():.4f}")
+```
+
+### Deal History Analysis
+
+```python
+with client:
+    # Collect entry deals for analysis
+    deals_df = client.collect_entry_deals_as_df(
+        symbol="EURUSD",
+        history_seconds=3600,  # Last hour
+        index_keys="ticket"
+    )
+
+    if not deals_df.empty:
+        print(f"Entry deals found: {len(deals_df)}")
+        print(f"Deal types: {deals_df['type'].value_counts()}")
+```
+
 ## Integration with Mt5DataClient
 
 Since Mt5TradingClient inherits from Mt5DataClient, all data retrieval methods are available:
@@ -204,14 +371,25 @@ Since Mt5TradingClient inherits from Mt5DataClient, all data retrieval methods a
 with Mt5TradingClient(config=config) as client:
     # Get current positions as DataFrame
     positions_df = client.get_positions_as_df()
-    
+
     # Analyze positions
     if not positions_df.empty:
         # Calculate total exposure
         total_volume = positions_df['volume'].sum()
-        
+
         # Close losing positions
         losing_positions = positions_df[positions_df['profit'] < 0]
         for symbol in losing_positions['symbol'].unique():
             client.close_open_positions(symbol)
-```
+
+    # Risk management with margin calculations
+    for symbol in ["EURUSD", "GBPUSD", "USDJPY"]:
+        # Calculate current margin usage
+        current_ratio = client.calculate_new_position_margin_ratio(symbol)
+        print(f"{symbol} current margin ratio: {current_ratio:.2%}")
+
+        # Calculate maximum safe position size
+        safe_margin = 500.0  # USD
+        max_safe_volume = client.calculate_volume_by_margin(symbol, safe_margin, "BUY")
+        print(f"{symbol} max safe volume: {max_safe_volume}")
+```

{pdmt5-0.1.5 → pdmt5-0.1.6}/pdmt5/trading.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from datetime import timedelta
+from math import floor
 from typing import TYPE_CHECKING, Any, Literal
 
 from pydantic import ConfigDict, Field
@@ -263,41 +264,60 @@ class Mt5TradingClient(Mt5DataClient):
                 )
                 return []
 
-    def calculate_minimum_order_margins(self, symbol: str) -> dict[str, float]:
-        """Calculate minimum order margins for a given symbol.
+    def calculate_minimum_order_margin(
+        self,
+        symbol: str,
+        order_side: Literal["BUY", "SELL"],
+    ) -> dict[str, float]:
+        """Calculate the minimum order margins for a given symbol.
 
         Args:
-            symbol: Symbol for which to calculate minimum order margins.
+            symbol: Symbol for which to calculate the minimum order margins.
+            order_side: Optional side of the order, either "BUY" or "SELL".
 
         Returns:
-            Dictionary with margin information.
-
-        Raises:
-            Mt5TradingError: If margin calculation fails.
+            Dictionary with minimum volume and margin for the specified order side.
         """
         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.order_calc_margin(
-            action=self.mt5.ORDER_TYPE_BUY,
+        return {
+            "volume": symbol_info["volume_min"],
+            "margin": self.order_calc_margin(
+                action=getattr(self.mt5, f"ORDER_TYPE_{order_side.upper()}"),
+                symbol=symbol,
+                volume=symbol_info["volume_min"],
+                price=(
+                    symbol_info_tick["bid"]
+                    if order_side == "SELL"
+                    else symbol_info_tick["ask"]
+                ),
+            ),
+        }
+
+    def calculate_volume_by_margin(
+        self,
+        symbol: str,
+        margin: float,
+        order_side: Literal["BUY", "SELL"],
+    ) -> float:
+        """Calculate volume based on margin for a given symbol and order side.
+
+        Args:
+            symbol: Symbol for which to calculate the volume.
+            margin: Margin amount to use for the calculation.
+            order_side: Side of the order, either "BUY" or "SELL".
+
+        Returns:
+            Calculated volume as a float.
+        """
+        min_order_margin_dict = self.calculate_minimum_order_margin(
             symbol=symbol,
-            volume=symbol_info["volume_min"],
-            price=symbol_info_tick["ask"],
+            order_side=order_side,
         )
-        min_bid_order_margin = self.order_calc_margin(
-            action=self.mt5.ORDER_TYPE_SELL,
-            symbol=symbol,
-            volume=symbol_info["volume_min"],
-            price=symbol_info_tick["bid"],
+        return (
+            floor(margin / min_order_margin_dict["margin"])
+            * min_order_margin_dict["volume"]
         )
-        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)
 
     def calculate_spread_ratio(
         self,
@@ -477,15 +497,15 @@ class Mt5TradingClient(Mt5DataClient):
     def calculate_new_position_margin_ratio(
         self,
         symbol: str,
-        new_side: Literal["BUY", "SELL"] | None = None,
-        new_volume: float = 0,
+        new_position_side: Literal["BUY", "SELL"] | None = None,
+        new_position_volume: float = 0,
     ) -> float:
         """Calculate the margin ratio for a new position.
 
         Args:
             symbol: Symbol for which to calculate the margin ratio.
-            new_side: Side of the new position, either "BUY" or "SELL".
-            new_volume: Volume of the new position.
+            new_position_side: Side of the new position, either "BUY" or "SELL".
+            new_position_volume: Volume of the new position.
 
         Returns:
             float: Margin ratio for the new position as a fraction of account equity.
@@ -499,20 +519,20 @@ class Mt5TradingClient(Mt5DataClient):
                 positions_df["signed_margin"].sum() if positions_df.size else 0
             )
             symbol_info_tick = self.symbol_info_tick_as_dict(symbol=symbol)
-            if new_volume == 0:
+            if not (new_position_side and new_position_volume):
                 new_signed_margin = 0
-            elif new_side == "BUY":
+            elif new_position_side.upper() == "BUY":
                 new_signed_margin = self.order_calc_margin(
                     action=self.mt5.ORDER_TYPE_BUY,
                     symbol=symbol,
-                    volume=new_volume,
+                    volume=new_position_volume,
                     price=symbol_info_tick["ask"],
                 )
-            elif new_side == "SELL":
+            elif new_position_side.upper() == "SELL":
                 new_signed_margin = -self.order_calc_margin(
                     action=self.mt5.ORDER_TYPE_SELL,
                     symbol=symbol,
-                    volume=new_volume,
+                    volume=new_position_volume,
                     price=symbol_info_tick["bid"],
                 )
             else:

{pdmt5-0.1.5 → pdmt5-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pdmt5"
-version = "0.1.5"
+version = "0.1.6"
 description = "Pandas-based data handler for MetaTrader 5"
 authors = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 maintainers = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]

{pdmt5-0.1.5 → pdmt5-0.1.6}/test/test_trading.py

@@ -845,11 +845,11 @@ class TestMt5TradingClient:
         mock_mt5_import.order_check.assert_called_once()
         mock_mt5_import.order_send.assert_not_called()
 
-    def test_calculate_minimum_order_margins_success(
+    def test_calculate_minimum_order_margin_buy_success(
         self,
         mock_mt5_import: ModuleType,
     ) -> None:
-        """Test successful calculation of minimum order margins."""
+        """Test successful calculation of minimum order margin for BUY orders."""
         client = Mt5TradingClient(mt5=mock_mt5_import)
         mock_mt5_import.initialize.return_value = True
         client.initialize()
@@ -866,33 +866,24 @@ class TestMt5TradingClient:
             "bid": 1.0998,
         }
 
-        # Mock order_calc_margin to return successful results
-        mock_mt5_import.order_calc_margin.side_effect = [100.5, 99.8]
+        # Mock order_calc_margin to return successful result
+        mock_mt5_import.order_calc_margin.return_value = 100.5
 
-        result = client.calculate_minimum_order_margins("EURUSD")
+        result = client.calculate_minimum_order_margin("EURUSD", "BUY")
 
-        assert result == {"ask": 100.5, "bid": 99.8}
-        assert mock_mt5_import.order_calc_margin.call_count == 2
+        assert result == {"volume": 0.01, "margin": 100.5}
+        mock_mt5_import.order_calc_margin.assert_called_once_with(
+            mock_mt5_import.ORDER_TYPE_BUY,
+            "EURUSD",
+            0.01,
+            1.1000,
+        )
 
-        # Verify first call (buy order)
-        first_call = mock_mt5_import.order_calc_margin.call_args_list[0]
-        assert first_call[0][0] == mock_mt5_import.ORDER_TYPE_BUY  # action
-        assert first_call[0][1] == "EURUSD"  # symbol
-        assert first_call[0][2] == 0.01  # volume
-        assert first_call[0][3] == 1.1000  # price
-
-        # Verify second call (sell order)
-        second_call = mock_mt5_import.order_calc_margin.call_args_list[1]
-        assert second_call[0][0] == mock_mt5_import.ORDER_TYPE_SELL  # action
-        assert second_call[0][1] == "EURUSD"  # symbol
-        assert second_call[0][2] == 0.01  # volume
-        assert second_call[0][3] == 1.0998  # price
-
-    def test_calculate_minimum_order_margins_failure_ask(
+    def test_calculate_minimum_order_margin_sell_success(
         self,
         mock_mt5_import: ModuleType,
     ) -> None:
-        """Test failed calculation of minimum order margins - ask margin fails."""
+        """Test successful calculation of minimum order margin for SELL orders."""
         client = Mt5TradingClient(mt5=mock_mt5_import)
         mock_mt5_import.initialize.return_value = True
         client.initialize()
@@ -909,17 +900,24 @@ class TestMt5TradingClient:
             "bid": 1.0998,
         }
 
-        # Mock order_calc_margin to return None for ask margin
-        mock_mt5_import.order_calc_margin.side_effect = [None, 99.8]
+        # Mock order_calc_margin to return successful result
+        mock_mt5_import.order_calc_margin.return_value = 99.8
 
-        with pytest.raises(Mt5RuntimeError):
-            client.calculate_minimum_order_margins("EURUSD")
+        result = client.calculate_minimum_order_margin("EURUSD", "SELL")
 
-    def test_calculate_minimum_order_margins_failure_bid(
+        assert result == {"volume": 0.01, "margin": 99.8}
+        mock_mt5_import.order_calc_margin.assert_called_once_with(
+            mock_mt5_import.ORDER_TYPE_SELL,
+            "EURUSD",
+            0.01,
+            1.0998,
+        )
+
+    def test_calculate_volume_by_margin_buy_success(
         self,
         mock_mt5_import: ModuleType,
     ) -> None:
-        """Test failed calculation of minimum order margins - bid margin fails."""
+        """Test successful calculation of volume by margin for BUY orders."""
         client = Mt5TradingClient(mt5=mock_mt5_import)
         mock_mt5_import.initialize.return_value = True
         client.initialize()
@@ -936,17 +934,20 @@ class TestMt5TradingClient:
             "bid": 1.0998,
         }
 
-        # Mock order_calc_margin to return None for bid margin
-        mock_mt5_import.order_calc_margin.side_effect = [100.5, None]
+        # Mock order_calc_margin to return margin for minimum volume
+        mock_mt5_import.order_calc_margin.return_value = 100.5
+
+        result = client.calculate_volume_by_margin("EURUSD", 1000.0, "BUY")
 
-        with pytest.raises(Mt5RuntimeError):
-            client.calculate_minimum_order_margins("EURUSD")
+        # Should return floor(1000 / 100.5) * 0.01 = 9 * 0.01 = 0.09
+        expected_volume = 9 * 0.01
+        assert result == expected_volume
 
-    def test_calculate_minimum_order_margins_failure_both(
+    def test_calculate_volume_by_margin_sell_success(
         self,
         mock_mt5_import: ModuleType,
     ) -> None:
-        """Test failed calculation of minimum order margins - both margins fail."""
+        """Test successful calculation of volume by margin for SELL orders."""
         client = Mt5TradingClient(mt5=mock_mt5_import)
         mock_mt5_import.initialize.return_value = True
         client.initialize()
@@ -963,11 +964,14 @@ class TestMt5TradingClient:
             "bid": 1.0998,
         }
 
-        # Mock order_calc_margin to return 0.0 for both margins (indicates failure)
-        mock_mt5_import.order_calc_margin.side_effect = [0.0, 0.0]
+        # Mock order_calc_margin to return margin for minimum volume
+        mock_mt5_import.order_calc_margin.return_value = 99.8
 
-        with pytest.raises(Mt5TradingError):
-            client.calculate_minimum_order_margins("EURUSD")
+        result = client.calculate_volume_by_margin("EURUSD", 500.0, "SELL")
+
+        # Should return floor(500 / 99.8) * 0.01 = 5 * 0.01 = 0.05
+        expected_volume = 5 * 0.01
+        assert result == expected_volume
 
     def test_calculate_spread_ratio(
         self,
@@ -1358,7 +1362,7 @@ class TestMt5TradingClient:
         }
 
         result = client.calculate_new_position_margin_ratio(
-            symbol="EURUSD", new_side="BUY", new_volume=0.1
+            symbol="EURUSD", new_position_side="BUY", new_position_volume=0.1
         )
 
         assert result == 0.0
@@ -1409,7 +1413,7 @@ class TestMt5TradingClient:
         mock_mt5_import.order_calc_margin.return_value = 1000.0
 
         result = client.calculate_new_position_margin_ratio(
-            symbol="EURUSD", new_side="BUY", new_volume=0.1
+            symbol="EURUSD", new_position_side="BUY", new_position_volume=0.1
         )
 
         # Should return (new_margin + current_margin) / equity
@@ -1444,7 +1448,7 @@ class TestMt5TradingClient:
         mock_mt5_import.order_calc_margin.return_value = 1000.0
 
         result = client.calculate_new_position_margin_ratio(
-            symbol="EURUSD", new_side="SELL", new_volume=0.1
+            symbol="EURUSD", new_position_side="SELL", new_position_volume=0.1
         )
 
         # Should return abs(-new_margin / equity) for sell
@@ -1475,10 +1479,10 @@ class TestMt5TradingClient:
         }
 
         result = client.calculate_new_position_margin_ratio(
-            symbol="EURUSD", new_side="BUY", new_volume=0
+            symbol="EURUSD", new_position_side="BUY", new_position_volume=0
         )
 
-        # Should return 0 since new_volume is 0
+        # Should return 0 since new_position_volume is 0
         assert result == 0.0
 
     def test_calculate_new_position_margin_ratio_invalid_side(
@@ -1505,12 +1509,44 @@ class TestMt5TradingClient:
         }
 
         result = client.calculate_new_position_margin_ratio(
-            symbol="EURUSD", new_side=None, new_volume=0.1
+            symbol="EURUSD", new_position_side=None, new_position_volume=0.1
         )
 
         # Should return 0 since side is invalid
         assert result == 0.0
 
+    def test_calculate_new_position_margin_ratio_invalid_side_string(
+        self, mock_mt5_import: ModuleType
+    ) -> None:
+        """Test calculating margin ratio with invalid side string."""
+        client = Mt5TradingClient(mt5=mock_mt5_import)
+        mock_mt5_import.initialize.return_value = True
+        client.initialize()
+
+        # Mock account info
+        mock_mt5_import.account_info.return_value._asdict.return_value = {
+            "equity": 10000.0,
+        }
+
+        # Mock empty positions
+        mock_mt5_import.positions_get.return_value = []
+
+        # Mock symbol tick info
+        mock_mt5_import.symbol_info_tick.return_value._asdict.return_value = {
+            "time": pd.Timestamp("2009-02-14 00:31:30"),
+            "ask": 1.1002,
+            "bid": 1.1000,
+        }
+
+        result = client.calculate_new_position_margin_ratio(
+            symbol="EURUSD",
+            new_position_side="INVALID",  # type: ignore[arg-type]
+            new_position_volume=0.1,
+        )
+
+        # Should return 0 since side is invalid string
+        assert result == 0.0
+
     def test_update_sltp_for_open_positions(self, mock_mt5_import: ModuleType) -> None:
         """Test update_sltp_for_open_positions method."""
         client = Mt5TradingClient(mt5=mock_mt5_import)

{pdmt5-0.1.5 → pdmt5-0.1.6}/uv.lock

@@ -613,7 +613,7 @@ wheels = [
 
 [[package]]
 name = "pdmt5"
-version = "0.1.5"
+version = "0.1.6"
 source = { editable = "." }
 dependencies = [
     { name = "metatrader5", marker = "sys_platform == 'win32'" },