pdmt5 0.1.4__tar.gz → 0.1.6__tar.gz

{pdmt5-0.1.4 → pdmt5-0.1.6}/.claude/settings.json

@@ -6,10 +6,10 @@
         "hooks": [
           {
             "type": "command",
-            "command": "uv run ruff check --fix . && uv run ruff format . && uv run pyright . && uv run pytest"
+            "command": "uv run ruff format . && uv run ruff check --fix . && uv run pyright . && uv run pytest"
           }
         ]
       }
     ]
   }
-}
+}

{pdmt5-0.1.4 → 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.4 → pdmt5-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdmt5
-Version: 0.1.4
+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>
@@ -29,7 +29,6 @@ Pandas-based data handler for MetaTrader 5
 [![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Platform](https://img.shields.io/badge/platform-Windows-blue.svg)](https://www.microsoft.com/windows)
-[![Version](https://img.shields.io/badge/version-0.1.4-green.svg)](https://github.com/dceoy/pdmt5)
 
 ## Overview
 
@@ -43,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,10 +196,13 @@ Advanced trading operations client that extends Mt5DataClient:
   - `dry_run` - Test mode flag for simulating trades without execution
 - **Position Management**:
   - `close_open_positions()` - Close all positions for specified symbol(s)
-  - `send_or_check_order()` - Execute or validate orders based on dry_run mode
-- **Market Analysis**:
-  - `calculate_minimum_order_margins()` - Calculate minimum required margins for buy/sell orders
+  - `place_market_order()` - Place market orders with configurable side, volume, and execution modes
+  - `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**:
   - `fetch_latest_rates_as_df()` - Get recent OHLC data with timeframe strings (e.g., "M1", "H1", "D1")
   - `fetch_latest_ticks_as_df()` - Get tick data for specified seconds around last tick
@@ -288,18 +292,52 @@ from pdmt5 import Mt5TradingClient
 
 # Create trading client with specific order filling mode
 with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
+    # Place a market buy order
+    order_result = trader.place_market_order(
+        symbol="EURUSD",
+        volume=0.1,
+        order_side="BUY",
+        order_filling_mode="IOC",  # Immediate or Cancel
+        order_time_mode="GTC"      # Good Till Cancelled
+    )
+    print(f"Order placed: {order_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_position_side="SELL",
+        new_position_volume=0.2
+    )
+    print(f"New position margin ratio: {margin_ratio:.2%}")
+
     # Close all EURUSD positions
     results = trader.close_open_positions(symbols="EURUSD")
 
     if results:
-        for result in results:
-            print(f"Closed position {result['position']} with result: {result['retcode']}")
+        for symbol, close_results in results.items():
+            for result in close_results:
+                print(f"Closed position {result.get('position')} with result: {result['retcode']}")
 
     # Using dry run mode for testing
     trader_dry = Mt5TradingClient(config=config, dry_run=True)
     with trader_dry:
-        # Test closing positions without actual execution
-        test_results = trader_dry.close_open_positions(symbols=["EURUSD", "GBPUSD"])
+        # Test placing an order without actual execution
+        test_order = trader_dry.place_market_order(
+            symbol="GBPUSD",
+            volume=0.1,
+            order_side="SELL",
+            dry_run=True  # Override instance setting
+        )
+        print(f"Test order validation: {test_order['retcode']}")
 ```
 
 ### Market Analysis with Mt5TradingClient
@@ -310,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.4 → pdmt5-0.1.6}/README.md

@@ -6,7 +6,6 @@ Pandas-based data handler for MetaTrader 5
 [![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Platform](https://img.shields.io/badge/platform-Windows-blue.svg)](https://www.microsoft.com/windows)
-[![Version](https://img.shields.io/badge/version-0.1.4-green.svg)](https://github.com/dceoy/pdmt5)
 
 ## Overview
 
@@ -20,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,10 +173,13 @@ Advanced trading operations client that extends Mt5DataClient:
   - `dry_run` - Test mode flag for simulating trades without execution
 - **Position Management**:
   - `close_open_positions()` - Close all positions for specified symbol(s)
-  - `send_or_check_order()` - Execute or validate orders based on dry_run mode
-- **Market Analysis**:
-  - `calculate_minimum_order_margins()` - Calculate minimum required margins for buy/sell orders
+  - `place_market_order()` - Place market orders with configurable side, volume, and execution modes
+  - `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**:
   - `fetch_latest_rates_as_df()` - Get recent OHLC data with timeframe strings (e.g., "M1", "H1", "D1")
   - `fetch_latest_ticks_as_df()` - Get tick data for specified seconds around last tick
@@ -265,18 +269,52 @@ from pdmt5 import Mt5TradingClient
 
 # Create trading client with specific order filling mode
 with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
+    # Place a market buy order
+    order_result = trader.place_market_order(
+        symbol="EURUSD",
+        volume=0.1,
+        order_side="BUY",
+        order_filling_mode="IOC",  # Immediate or Cancel
+        order_time_mode="GTC"      # Good Till Cancelled
+    )
+    print(f"Order placed: {order_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_position_side="SELL",
+        new_position_volume=0.2
+    )
+    print(f"New position margin ratio: {margin_ratio:.2%}")
+
     # Close all EURUSD positions
     results = trader.close_open_positions(symbols="EURUSD")
 
     if results:
-        for result in results:
-            print(f"Closed position {result['position']} with result: {result['retcode']}")
+        for symbol, close_results in results.items():
+            for result in close_results:
+                print(f"Closed position {result.get('position')} with result: {result['retcode']}")
 
     # Using dry run mode for testing
     trader_dry = Mt5TradingClient(config=config, dry_run=True)
     with trader_dry:
-        # Test closing positions without actual execution
-        test_results = trader_dry.close_open_positions(symbols=["EURUSD", "GBPUSD"])
+        # Test placing an order without actual execution
+        test_order = trader_dry.place_market_order(
+            symbol="GBPUSD",
+            volume=0.1,
+            order_side="SELL",
+            dry_run=True  # Override instance setting
+        )
+        print(f"Test order validation: {test_order['retcode']}")
 ```
 
 ### Market Analysis with Mt5TradingClient
@@ -287,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.4 → 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}")
+```