pdmt5 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

pdmt5/trading.py

@@ -31,12 +31,11 @@ class Mt5TradingClient(Mt5DataClient):
         description="Order filling mode: 'IOC' (Immediate or Cancel), "
         "'FOK' (Fill or Kill), 'RETURN' (Return if not filled)",
     )
-    dry_run: bool = Field(default=False, description="Enable dry run mode for testing.")
 
     def close_open_positions(
         self,
         symbols: str | list[str] | tuple[str, ...] | None = None,
-        dry_run: bool | None = None,
+        dry_run: bool = False,
         **kwargs: Any,  # noqa: ANN401
     ) -> dict[str, list[dict[str, Any]]]:
         """Close all open positions for specified symbols.
@@ -44,8 +43,7 @@ class Mt5TradingClient(Mt5DataClient):
         Args:
             symbols: Optional symbol or list of symbols to filter positions.
                 If None, all symbols will be considered.
-            dry_run: Optional flag to enable dry run mode. If None, uses the instance's
-                `dry_run` attribute.
+            dry_run: If True, only check the order without sending it.
             **kwargs: Additional keyword arguments for request parameters.
 
         Returns:
@@ -67,15 +65,14 @@ class Mt5TradingClient(Mt5DataClient):
     def _fetch_and_close_position(
         self,
         symbol: str | None = None,
-        dry_run: bool | None = None,
+        dry_run: bool = False,
         **kwargs: Any,  # noqa: ANN401
     ) -> list[dict[str, Any]]:
         """Close all open positions for a specific symbol.
 
         Args:
             symbol: Optional symbol filter.
-            dry_run: Optional flag to enable dry run mode. If None, uses the instance's
-                `dry_run` attribute.
+            dry_run: If True, only check the order without sending it.
             **kwargs: Additional keyword arguments for request parameters.
 
         Returns:
@@ -92,7 +89,7 @@ class Mt5TradingClient(Mt5DataClient):
                 f"ORDER_FILLING_{self.order_filling_mode}",
             )
             return [
-                self.send_or_check_order(
+                self._send_or_check_order(
                     request={
                         "action": self.mt5.TRADE_ACTION_DEAL,
                         "symbol": p["symbol"],
@@ -112,17 +109,16 @@ class Mt5TradingClient(Mt5DataClient):
                 for p in positions_dict
             ]
 
-    def send_or_check_order(
+    def _send_or_check_order(
         self,
         request: dict[str, Any],
-        dry_run: bool | None = None,
+        dry_run: bool = False,
     ) -> 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.
+            dry_run: If True, only check the order without sending it.
 
         Returns:
             Dictionary with operation result.
@@ -131,17 +127,15 @@ class Mt5TradingClient(Mt5DataClient):
             Mt5TradingError: If the order operation fails.
         """
         self.logger.debug("request: %s", request)
-        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:
+        if 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 is_dry_run) and retcode == self.mt5.TRADE_RETCODE_DONE) or (
-            is_dry_run and retcode == 0
+        if ((not dry_run) and retcode == self.mt5.TRADE_RETCODE_DONE) or (
+            dry_run and retcode == 0
         ):
             self.logger.info("response: %s", response)
             return response
@@ -159,6 +153,116 @@ class Mt5TradingClient(Mt5DataClient):
             error_message = f"{order_func}() failed and aborted. <= `{comment}`"
             raise Mt5TradingError(error_message)
 
+    def place_market_order(
+        self,
+        symbol: str,
+        volume: float,
+        order_side: Literal["BUY", "SELL"],
+        order_filling_mode: Literal["IOC", "FOK", "RETURN"] = "IOC",
+        order_time_mode: Literal["GTC", "DAY", "SPECIFIED", "SPECIFIED_DAY"] = "GTC",
+        dry_run: bool = False,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> dict[str, Any]:
+        """Send or check an order request to place a market order.
+
+        Args:
+            symbol: Symbol for the order.
+            volume: Volume of the order.
+            order_side: Side of the order, either "BUY" or "SELL".
+            order_filling_mode: Order filling mode, either "IOC", "FOK", or "RETURN".
+            order_time_mode: Order time mode, either "GTC", "DAY", "SPECIFIED",
+                or "SPECIFIED_DAY".
+            dry_run: If True, only check the order without sending it.
+            **kwargs: Additional keyword arguments for request parameters.
+
+        Returns:
+            Dictionary with operation result.
+        """
+        return self._send_or_check_order(
+            request={
+                "action": self.mt5.TRADE_ACTION_DEAL,
+                "symbol": symbol,
+                "volume": volume,
+                "type": getattr(self.mt5, f"ORDER_TYPE_{order_side.upper()}"),
+                "type_filling": getattr(
+                    self.mt5, f"ORDER_FILLING_{order_filling_mode.upper()}"
+                ),
+                "type_time": getattr(self.mt5, f"ORDER_TIME_{order_time_mode.upper()}"),
+                **kwargs,
+            },
+            dry_run=dry_run,
+        )
+
+    def update_sltp_for_open_positions(
+        self,
+        symbol: str,
+        stop_loss: float | None = None,
+        take_profit: float | None = None,
+        tickets: list[int] | None = None,
+        dry_run: bool = False,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> list[dict[str, Any]]:
+        """Change Stop Loss and Take Profit for open positions.
+
+        Args:
+            symbol: Symbol for the position.
+            stop_loss: New Stop Loss price. If None, it will not be changed.
+            take_profit: New Take Profit price. If None, it will not be changed.
+            tickets: List of position tickets to filter positions. If None, all open
+                positions for the symbol will be considered.
+            dry_run: If True, only check the order without sending it.
+            **kwargs: Additional keyword arguments for request parameters.
+
+        Returns:
+            List of dictionaries with operation results for each updated position.
+        """
+        positions_df = self.positions_get_as_df(symbol=symbol)
+        if positions_df.empty:
+            self.logger.warning("No open positions found for symbol: %s", symbol)
+            return []
+        elif tickets:
+            filtered_positions_df = positions_df.pipe(
+                lambda d: d[d["ticket"].isin(tickets)]
+            )
+        else:
+            filtered_positions_df = positions_df
+        if filtered_positions_df.empty:
+            self.logger.warning(
+                "No open positions found for symbol: %s with specified tickets: %s",
+                symbol,
+                tickets,
+            )
+            return []
+        else:
+            symbol_info = self.symbol_info_as_dict(symbol=symbol)
+            sl = round(stop_loss, symbol_info["digits"]) if stop_loss else None
+            tp = round(take_profit, symbol_info["digits"]) if take_profit else None
+            order_requests = [
+                {
+                    "action": self.mt5.TRADE_ACTION_SLTP,
+                    "symbol": p["symbol"],
+                    "position": p["ticket"],
+                    "sl": (sl or p["sl"]),
+                    "tp": (tp or p["tp"]),
+                    **kwargs,
+                }
+                for _, p in filtered_positions_df.iterrows()
+                if sl != p["sl"] or tp != p["tp"]
+            ]
+            if order_requests:
+                return [
+                    self._send_or_check_order(request=r, dry_run=dry_run)
+                    for r in order_requests
+                ]
+            else:
+                self.logger.info(
+                    "No positions to update for symbol: %s with SL: %s and TP: %s",
+                    symbol,
+                    sl,
+                    tp,
+                )
+                return []
+
     def calculate_minimum_order_margins(self, symbol: str) -> dict[str, float]:
         """Calculate minimum order margins for a given symbol.
 
@@ -214,7 +318,7 @@ class Mt5TradingClient(Mt5DataClient):
             * 2
         )
 
-    def copy_latest_rates_as_df(
+    def fetch_latest_rates_as_df(
         self,
         symbol: str,
         granularity: str = "M1",
@@ -251,7 +355,7 @@ class Mt5TradingClient(Mt5DataClient):
                 index_keys=index_keys,
             )
 
-    def copy_latest_ticks_as_df(
+    def fetch_latest_ticks_as_df(
         self,
         symbol: str,
         seconds: int = 300,
@@ -275,3 +379,144 @@ class Mt5TradingClient(Mt5DataClient):
             flags=self.mt5.COPY_TICKS_ALL,
             index_keys=index_keys,
         )
+
+    def collect_entry_deals_as_df(
+        self,
+        symbol: str,
+        history_seconds: int = 3600,
+        index_keys: str | None = "ticket",
+    ) -> pd.DataFrame:
+        """Collect entry deals as a DataFrame.
+
+        Args:
+            symbol: Symbol to collect entry deals for.
+            history_seconds: Time range in seconds to fetch deals around the last tick.
+            index_keys: Optional index keys for the DataFrame.
+
+        Returns:
+            pd.DataFrame: Entry deals with time index.
+        """
+        last_tick_time = self.symbol_info_tick_as_dict(symbol=symbol)["time"]
+        deals_df = self.history_deals_get_as_df(
+            date_from=(last_tick_time - timedelta(seconds=history_seconds)),
+            date_to=(last_tick_time + timedelta(seconds=history_seconds)),
+            symbol=symbol,
+            index_keys=index_keys,
+        )
+        if deals_df.empty:
+            return deals_df
+        else:
+            return deals_df.pipe(
+                lambda d: d[
+                    d["entry"]
+                    & d["type"].isin({self.mt5.DEAL_TYPE_BUY, self.mt5.DEAL_TYPE_SELL})
+                ]
+            )
+
+    def fetch_positions_with_metrics_as_df(
+        self,
+        symbol: str,
+    ) -> pd.DataFrame:
+        """Fetch open positions as a DataFrame with additional metrics.
+
+        Args:
+            symbol: Symbol to fetch positions for.
+
+        Returns:
+            pd.DataFrame: DataFrame containing open positions with additional metrics.
+        """
+        positions_df = self.positions_get_as_df(symbol=symbol)
+        if positions_df.empty:
+            return positions_df
+        else:
+            symbol_info_tick = self.symbol_info_tick_as_dict(symbol=symbol)
+            ask_margin = self.order_calc_margin(
+                action=self.mt5.ORDER_TYPE_BUY,
+                symbol=symbol,
+                volume=1,
+                price=symbol_info_tick["ask"],
+            )
+            bid_margin = self.order_calc_margin(
+                action=self.mt5.ORDER_TYPE_SELL,
+                symbol=symbol,
+                volume=1,
+                price=symbol_info_tick["bid"],
+            )
+            return (
+                positions_df.assign(
+                    elapsed_seconds=lambda d: (
+                        symbol_info_tick["time"] - d["time"]
+                    ).dt.total_seconds(),
+                    underlier_increase_ratio=lambda d: (
+                        d["price_current"] / d["price_open"] - 1
+                    ),
+                    buy=lambda d: (d["type"] == self.mt5.POSITION_TYPE_BUY),
+                    sell=lambda d: (d["type"] == self.mt5.POSITION_TYPE_SELL),
+                )
+                .assign(
+                    buy_i=lambda d: d["buy"].astype(int),
+                    sell_i=lambda d: d["sell"].astype(int),
+                )
+                .assign(
+                    sign=lambda d: (d["buy_i"] - d["sell_i"]),
+                    margin=lambda d: (
+                        (d["buy_i"] * ask_margin + d["sell_i"] * bid_margin)
+                        * d["volume"]
+                    ),
+                )
+                .assign(
+                    signed_volume=lambda d: (d["volume"] * d["sign"]),
+                    signed_margin=lambda d: (d["margin"] * d["sign"]),
+                    underlier_profit_ratio=lambda d: (
+                        d["underlier_increase_ratio"] * d["sign"]
+                    ),
+                )
+                .drop(columns=["buy_i", "sell_i", "sign", "underlier_increase_ratio"])
+            )
+
+    def calculate_new_position_margin_ratio(
+        self,
+        symbol: str,
+        new_side: Literal["BUY", "SELL"] | None = None,
+        new_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.
+
+        Returns:
+            float: Margin ratio for the new position as a fraction of account equity.
+        """
+        account_info = self.account_info_as_dict()
+        if not account_info["equity"]:
+            return 0.0
+        else:
+            positions_df = self.fetch_positions_with_metrics_as_df(symbol=symbol)
+            current_signed_margin = (
+                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:
+                new_signed_margin = 0
+            elif new_side == "BUY":
+                new_signed_margin = self.order_calc_margin(
+                    action=self.mt5.ORDER_TYPE_BUY,
+                    symbol=symbol,
+                    volume=new_volume,
+                    price=symbol_info_tick["ask"],
+                )
+            elif new_side == "SELL":
+                new_signed_margin = -self.order_calc_margin(
+                    action=self.mt5.ORDER_TYPE_SELL,
+                    symbol=symbol,
+                    volume=new_volume,
+                    price=symbol_info_tick["bid"],
+                )
+            else:
+                new_signed_margin = 0
+            return abs(
+                (new_signed_margin + current_signed_margin) / account_info["equity"]
+            )

pdmt5-0.1.5.dist-info/METADATA

@@ -0,0 +1,462 @@
+Metadata-Version: 2.4
+Name: pdmt5
+Version: 0.1.5
+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>
+Maintainer-email: dceoy <dceoy@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Requires-Dist: metatrader5>=5.0.4424; sys_platform == 'win32'
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: pydantic>=2.9.0
+Description-Content-Type: text/markdown
+
+# pdmt5
+
+Pandas-based data handler for MetaTrader 5
+
+[![CI/CD](https://github.com/dceoy/pdmt5/actions/workflows/ci.yml/badge.svg)](https://github.com/dceoy/pdmt5/actions/workflows/ci.yml)
+[![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)
+
+## Overview
+
+**pdmt5** is a Python package that provides a pandas-based interface for MetaTrader 5 (MT5), making it easier to work with financial market data in Python. It automatically converts MT5's native data structures into pandas DataFrames, enabling seamless integration with data science workflows.
+
+### Key Features
+
+- 📊 **Pandas Integration**: All data returned as pandas DataFrames for easy analysis
+- 🔧 **Type Safety**: Full type hints with strict pyright checking and pydantic validation
+- 🏦 **Comprehensive MT5 Coverage**: Account info, market data, tick data, orders, positions, and more
+- 🚀 **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
+
+## Requirements
+
+- **Operating System**: Windows (required by MetaTrader5 API)
+- **Python**: 3.11 or higher
+- **MetaTrader 5**: Terminal must be installed
+
+## Installation
+
+### From GitHub
+
+```bash
+git clone https://github.com/dceoy/pdmt5.git
+pip install -U --no-cache-dir ./pdmt5
+```
+
+### Using uv (recommended for development)
+
+```bash
+git clone https://github.com/dceoy/pdmt5.git
+cd pdmt5
+uv sync
+```
+
+## Quick Start
+
+```python
+import MetaTrader5 as mt5
+from datetime import datetime
+from pdmt5 import Mt5DataClient, Mt5Config
+
+# Configure connection
+config = Mt5Config(
+    login=12345678,
+    password="your_password",
+    server="YourBroker-Server",
+    timeout=60000
+)
+
+# Use as context manager
+with Mt5DataClient(config=config) as client:
+    # Get account information as DataFrame
+    account_info = client.account_info_as_df()
+    print(account_info)
+
+    # Get OHLCV data as DataFrame
+    rates = client.copy_rates_from_as_df(
+        symbol="EURUSD",
+        timeframe=mt5.TIMEFRAME_H1,
+        date_from=datetime(2024, 1, 1),
+        count=100
+    )
+    print(rates.head())
+
+    # Get current positions as DataFrame
+    positions = client.positions_get_as_df()
+    print(positions)
+```
+
+## Core Components
+
+### Mt5Client
+
+The base client wrapper for all MetaTrader5 operations with context manager support:
+
+- **Connection Management**:
+  - `initialize()` - Establish connection with MT5 terminal (with optional path, login, password, server, timeout)
+  - `login()` - Connect to trading account with credentials
+  - `shutdown()` - Close MT5 terminal connection
+  - Context manager support (`with` statement) for automatic initialization/cleanup
+- **Terminal Information**:
+  - `version()` - Get MT5 terminal version, build, and release date
+  - `last_error()` - Get last error code and description
+  - `account_info()` - Get current trading account information
+  - `terminal_info()` - Get terminal status and settings
+- **Symbol Operations**:
+  - `symbols_total()` - Get total number of financial instruments
+  - `symbols_get()` - Get all symbols or filter by group
+  - `symbol_info()` - Get detailed data on specific symbol
+  - `symbol_info_tick()` - Get last tick for symbol
+  - `symbol_select()` - Show/hide symbol in MarketWatch
+- **Market Depth**:
+  - `market_book_add()` - Subscribe to Market Depth events
+  - `market_book_get()` - Get current Market Depth data
+  - `market_book_release()` - Unsubscribe from Market Depth
+- **Market Data**:
+  - `copy_rates_from()` - Get bars from specified date
+  - `copy_rates_from_pos()` - Get bars from specified position
+  - `copy_rates_range()` - Get bars for date range
+  - `copy_ticks_from()` - Get ticks from specified date
+  - `copy_ticks_range()` - Get ticks for date range
+- **Order Operations**:
+  - `orders_total()` - Get number of active orders
+  - `orders_get()` - Get active orders with optional filters
+  - `order_calc_margin()` - Calculate required margin
+  - `order_calc_profit()` - Calculate potential profit
+  - `order_check()` - Check if order can be placed
+  - `order_send()` - Send order to trade server
+- **Position Operations**:
+  - `positions_total()` - Get number of open positions
+  - `positions_get()` - Get open positions with optional filters
+- **Trading History**:
+  - `history_orders_total()` - Get number of historical orders
+  - `history_orders_get()` - Get historical orders with filters
+  - `history_deals_total()` - Get number of historical deals
+  - `history_deals_get()` - Get historical deals with filters
+
+### Mt5DataClient
+
+Extends Mt5Client with pandas DataFrame and dictionary conversions:
+
+- **Enhanced Connection**:
+  - `initialize_and_login_mt5()` - Combined initialization and login with retry logic
+  - Configurable retry attempts via `retry_count` parameter
+- **DataFrame/Dictionary Conversions**: All methods have both `_as_df` and `_as_dict` variants:
+  - `version_as_dict/df()` - MT5 version information
+  - `last_error_as_dict/df()` - Last error details
+  - `account_info_as_dict/df()` - Account information
+  - `terminal_info_as_dict/df()` - Terminal information
+  - `symbols_get_as_dicts/df()` - Symbol list with optional group filter
+  - `symbol_info_as_dict/df()` - Single symbol information
+  - `symbol_info_tick_as_dict/df()` - Last tick data
+  - `market_book_get_as_dicts/df()` - Market depth data
+- **OHLCV Data Methods**:
+  - `copy_rates_from_as_dicts/df()` - Historical bars from date
+  - `copy_rates_from_pos_as_dicts/df()` - Historical bars from position
+  - `copy_rates_range_as_dicts/df()` - Historical bars for date range
+- **Tick Data Methods**:
+  - `copy_ticks_from_as_dicts/df()` - Historical ticks from date
+  - `copy_ticks_range_as_dicts/df()` - Historical ticks for date range
+- **Trading Data Methods**:
+  - `orders_get_as_dicts/df()` - Active orders with filters
+  - `order_check_as_dict/df()` - Order validation results
+  - `order_send_as_dict/df()` - Order execution results
+  - `positions_get_as_dicts/df()` - Open positions with filters
+  - `history_orders_get_as_dicts/df()` - Historical orders with date/ticket/position filters
+  - `history_deals_get_as_dicts/df()` - Historical deals with date/ticket/position filters
+- **Features**:
+  - Automatic time conversion to datetime objects
+  - Optional DataFrame indexing with `index_keys` parameter
+  - Input validation for dates, counts, and positions
+  - Pydantic-based configuration via `Mt5Config`
+
+### Mt5TradingClient
+
+Advanced trading operations client that extends Mt5DataClient:
+
+- **Trading Configuration**:
+  - `order_filling_mode` - Order execution mode: "IOC" (default), "FOK", or "RETURN"
+  - `dry_run` - Test mode flag for simulating trades without execution
+- **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
+  - `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
+  - `collect_entry_deals_as_df()` - Filter and collect entry deals (BUY/SELL) from history
+  - `fetch_positions_with_metrics_as_df()` - Get open positions with calculated metrics (elapsed time, margin, profit ratios)
+- **Features**:
+  - Smart order routing with configurable filling modes
+  - Comprehensive error handling with `Mt5TradingError`
+  - Support for batch operations on multiple symbols
+  - Automatic position closing with proper order type reversal
+  - Dry run mode for strategy testing without real trades
+
+### Configuration
+
+```python
+from pdmt5 import Mt5Config
+
+config = Mt5Config(
+    login=12345678,          # MT5 account number
+    password="password",     # MT5 password
+    server="Broker-Server",  # MT5 server name
+    timeout=60000           # Connection timeout in ms
+)
+```
+
+## Examples
+
+### Getting Historical Data
+
+```python
+import MetaTrader5 as mt5
+from datetime import datetime
+
+with Mt5DataClient(config=config) as client:
+    # Get last 1000 H1 bars for EURUSD as DataFrame
+    df = client.copy_rates_from_as_df(
+        symbol="EURUSD",
+        timeframe=mt5.TIMEFRAME_H1,
+        date_from=datetime.now(),
+        count=1000
+    )
+
+    # Data includes: time, open, high, low, close, tick_volume, spread, real_volume
+    print(df.columns)
+    print(df.describe())
+```
+
+### Working with Tick Data
+
+```python
+from datetime import datetime, timedelta
+
+with Mt5DataClient(config=config) as client:
+    # Get ticks for the last hour as DataFrame
+    ticks = client.copy_ticks_from_as_df(
+        symbol="EURUSD",
+        date_from=datetime.now() - timedelta(hours=1),
+        count=10000,
+        flags=mt5.COPY_TICKS_ALL
+    )
+
+    # Tick data includes: time, bid, ask, last, volume, flags
+    print(ticks.head())
+```
+
+### Analyzing Positions
+
+```python
+with Mt5DataClient(config=config) as client:
+    # Get all open positions as DataFrame
+    positions = client.positions_get_as_df()
+
+    if not positions.empty:
+        # Calculate summary statistics
+        summary = positions.groupby('symbol').agg({
+            'volume': 'sum',
+            'profit': 'sum',
+            'price_open': 'mean'
+        })
+        print(summary)
+```
+
+### Trading Operations
+
+```python
+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 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']}")
+
+    # Calculate margin ratio for a new position
+    margin_ratio = trader.calculate_new_position_margin_ratio(
+        symbol="EURUSD",
+        new_side="SELL",
+        new_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 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 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
+
+```python
+with Mt5TradingClient(config=config) as trader:
+    # Calculate spread ratio for EURUSD
+    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 recent OHLC data with custom timeframe
+    rates_df = trader.fetch_latest_rates_as_df(
+        symbol="EURUSD",
+        granularity="M15",  # 15-minute bars
+        count=100
+    )
+    print(rates_df.tail())
+
+    # Get tick data for the last 60 seconds
+    ticks_df = trader.fetch_latest_ticks_as_df(
+        symbol="EURUSD",
+        seconds=60
+    )
+    print(f"Received {len(ticks_df)} ticks")
+
+    # Collect entry deals for the last hour
+    deals_df = trader.collect_entry_deals_as_df(
+        symbol="EURUSD",
+        history_seconds=3600
+    )
+    if not deals_df.empty:
+        print(f"Found {len(deals_df)} entry deals")
+        print(deals_df[['time', 'type', 'volume', 'price']].head())
+
+    # Get positions with calculated metrics
+    positions_df = trader.fetch_positions_with_metrics_as_df("EURUSD")
+    if not positions_df.empty:
+        print(f"Open positions with metrics:")
+        print(positions_df[['ticket', 'volume', 'profit', 'elapsed_seconds', 'underlier_profit_ratio']].head())
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone repository
+git clone https://github.com/dceoy/pdmt5.git
+cd pdmt5
+
+# Install with uv
+uv sync
+
+# Run tests
+uv run pytest test/ -v
+
+# Run type checking
+uv run pyright .
+
+# Run linting
+uv run ruff check --fix .
+uv run ruff format .
+```
+
+### Code Quality
+
+This project maintains high code quality standards:
+
+- **Type Checking**: Strict mode with pyright
+- **Linting**: Comprehensive ruff configuration with 40+ rule categories
+- **Testing**: pytest with coverage tracking (minimum 90%)
+- **Documentation**: Google-style docstrings
+
+## Error Handling
+
+The package provides detailed error information:
+
+```python
+from pdmt5 import Mt5RuntimeError
+
+try:
+    with Mt5DataClient(config=config) as client:
+        data = client.copy_rates_from("INVALID", mt5.TIMEFRAME_H1, datetime.now(), 100)
+except Mt5RuntimeError as e:
+    print(f"MT5 Error: {e}")
+    print(f"Error code: {e.error_code}")
+    print(f"Description: {e.description}")
+```
+
+## Limitations
+
+- **Windows Only**: Due to MetaTrader5 API requirements
+- **MT5 Terminal Required**: The MetaTrader 5 terminal must be installed
+- **Single Thread**: MT5 API is not thread-safe
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Ensure tests pass and coverage is maintained
+4. Submit a pull request
+
+See [CLAUDE.md](CLAUDE.md) for development guidelines.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Daichi Narushima, Ph.D.
+
+## Acknowledgments
+
+- MetaTrader 5 for providing the Python API
+- The pandas community for the excellent data manipulation tools

{pdmt5-0.1.3.dist-info → pdmt5-0.1.5.dist-info}/RECORD

@@ -1,9 +1,9 @@
 pdmt5/__init__.py,sha256=QbSFrsi7_bgFzb-ma4DmmUjR90UvrqKMnRZq1wPRmoI,446
 pdmt5/dataframe.py,sha256=rUWtR23hrXBdBqzJhbOlIemNy73RrjSTZZJUhwoL6io,38084
 pdmt5/mt5.py,sha256=KgxHapIrh5b4L0wIOAQIjfXNZafalihbFrh9fhYHmrI,32254
-pdmt5/trading.py,sha256=FsLC_X_bwBnnQ9l54wPA4OlwD2HlO1RnPvOCnMopNNE,10113
+pdmt5/trading.py,sha256=TJjxq2PP2eIRM8pe4G0DzxLkLjOFR-0ZV0rpzDwl-TU,19488
 pdmt5/utils.py,sha256=Ll5Q3OE5h1A_sZ_qVEnOPGniFlT6_MmHfuu0zqeLdeU,3913
-pdmt5-0.1.3.dist-info/METADATA,sha256=UpjES_3YPgMHCpmX4da8ox0OlqJ36nE5B-cYNKvv2A8,9029
-pdmt5-0.1.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pdmt5-0.1.3.dist-info/licenses/LICENSE,sha256=iABrdaUGOBWLYotFupB_PGe8arV5o7rVhn-_vK6P704,1073
-pdmt5-0.1.3.dist-info/RECORD,,
+pdmt5-0.1.5.dist-info/METADATA,sha256=YjTgWZTyhoLtzbLii57WYM5UajB0pix15sM7CzhjgwY,16085
+pdmt5-0.1.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pdmt5-0.1.5.dist-info/licenses/LICENSE,sha256=iABrdaUGOBWLYotFupB_PGe8arV5o7rVhn-_vK6P704,1073
+pdmt5-0.1.5.dist-info/RECORD,,

pdmt5-0.1.3.dist-info/METADATA

@@ -1,306 +0,0 @@
-Metadata-Version: 2.4
-Name: pdmt5
-Version: 0.1.3
-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>
-Maintainer-email: dceoy <dceoy@users.noreply.github.com>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Financial and Insurance Industry
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Office/Business :: Financial :: Investment
-Requires-Python: >=3.11
-Requires-Dist: metatrader5>=5.0.4424; sys_platform == 'win32'
-Requires-Dist: pandas>=2.2.2
-Requires-Dist: pydantic>=2.9.0
-Description-Content-Type: text/markdown
-
-# pdmt5
-
-Pandas-based data handler for MetaTrader 5
-
-[![CI/CD](https://github.com/dceoy/pdmt5/actions/workflows/ci.yml/badge.svg)](https://github.com/dceoy/pdmt5/actions/workflows/ci.yml)
-[![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)
-
-## Overview
-
-**pdmt5** is a Python package that provides a pandas-based interface for MetaTrader 5 (MT5), making it easier to work with financial market data in Python. It automatically converts MT5's native data structures into pandas DataFrames, enabling seamless integration with data science workflows.
-
-### Key Features
-
-- 📊 **Pandas Integration**: All data returned as pandas DataFrames for easy analysis
-- 🔧 **Type Safety**: Full type hints with strict pyright checking and pydantic validation
-- 🏦 **Comprehensive MT5 Coverage**: Account info, market data, tick data, orders, positions, and more
-- 🚀 **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
-
-## Requirements
-
-- **Operating System**: Windows (required by MetaTrader5 API)
-- **Python**: 3.11 or higher
-- **MetaTrader 5**: Terminal must be installed
-
-## Installation
-
-### From GitHub
-
-```bash
-git clone https://github.com/dceoy/pdmt5.git
-pip install -U --no-cache-dir ./pdmt5
-```
-
-### Using uv (recommended for development)
-
-```bash
-git clone https://github.com/dceoy/pdmt5.git
-cd pdmt5
-uv sync
-```
-
-## Quick Start
-
-```python
-import MetaTrader5 as mt5
-from datetime import datetime
-from pdmt5 import Mt5DataClient, Mt5Config
-
-# Configure connection
-config = Mt5Config(
-    login=12345678,
-    password="your_password",
-    server="YourBroker-Server",
-    timeout=60000,
-    portable=False
-)
-
-# Use as context manager
-with Mt5DataClient(config=config) as client:
-    # Get account information as DataFrame
-    account_info = client.get_account_info_as_df()
-    print(account_info)
-
-    # Get OHLCV data as DataFrame
-    rates = client.copy_rates_from_as_df(
-        symbol="EURUSD",
-        timeframe=mt5.TIMEFRAME_H1,
-        date_from=datetime(2024, 1, 1),
-        count=100
-    )
-    print(rates.head())
-
-    # Get current positions as DataFrame
-    positions = client.get_positions_as_df()
-    print(positions)
-```
-
-## Core Components
-
-### Mt5Client
-
-The base client for MT5 operations with context manager support:
-
-- **Connection Management**: `initialize()`, `login()`, `shutdown()`
-- **Account & Terminal Info**: Access account details and terminal information
-- **Symbol Operations**: Get symbol information and market data
-- **Trading Operations**: Execute orders, manage positions and deals
-- **History Access**: Retrieve historical orders and deals
-
-### Mt5DataClient
-
-Extends Mt5Client with pandas DataFrame conversions:
-
-- **DataFrame Methods**: All data methods have `_as_df` variants returning DataFrames
-- **Dictionary Methods**: All data methods have `_as_dict` variants returning dictionaries
-- **Account Operations**: `get_account_info()`, `get_terminal_info()`
-- **Market Data**: `copy_rates_*()` methods for OHLCV data
-- **Tick Data**: `copy_ticks_*()` methods for tick-level data
-- **Trading Info**: `get_orders()`, `get_positions()`, `get_deals()`
-- **Symbol Info**: `get_symbols()`, `get_symbol_info()`
-
-### Mt5TradingClient
-
-Advanced trading operations interface that extends Mt5DataClient:
-
-- **Position Management**: `close_open_positions()` - Close positions by symbol
-- **Order Filling Modes**: IOC (Immediate or Cancel), FOK (Fill or Kill), or RETURN
-- **Dry Run Mode**: Test trading logic without executing real trades
-- **Full Trading Operations**: Includes all Mt5DataClient capabilities plus trading features
-
-### Configuration
-
-```python
-from pdmt5 import Mt5Config
-
-config = Mt5Config(
-    login=12345678,          # MT5 account number
-    password="password",     # MT5 password
-    server="Broker-Server",  # MT5 server name
-    timeout=60000,          # Connection timeout in ms
-    portable=False          # Use portable mode
-)
-```
-
-## Examples
-
-### Getting Historical Data
-
-```python
-import MetaTrader5 as mt5
-from datetime import datetime
-
-with Mt5DataClient(config=config) as client:
-    # Get last 1000 H1 bars for EURUSD as DataFrame
-    df = client.copy_rates_from_as_df(
-        symbol="EURUSD",
-        timeframe=mt5.TIMEFRAME_H1,
-        date_from=datetime.now(),
-        count=1000
-    )
-
-    # Data includes: time, open, high, low, close, tick_volume, spread, real_volume
-    print(df.columns)
-    print(df.describe())
-```
-
-### Working with Tick Data
-
-```python
-from datetime import datetime, timedelta
-
-with Mt5DataClient(config=config) as client:
-    # Get ticks for the last hour as DataFrame
-    ticks = client.copy_ticks_from_as_df(
-        symbol="EURUSD",
-        date_from=datetime.now() - timedelta(hours=1),
-        count=10000,
-        flags=mt5.COPY_TICKS_ALL
-    )
-
-    # Tick data includes: time, bid, ask, last, volume, flags
-    print(ticks.head())
-```
-
-### Analyzing Positions
-
-```python
-with Mt5DataClient(config=config) as client:
-    # Get all open positions as DataFrame
-    positions = client.get_positions_as_df()
-
-    if not positions.empty:
-        # Calculate summary statistics
-        summary = positions.groupby('symbol').agg({
-            'volume': 'sum',
-            'profit': 'sum',
-            'price_open': 'mean'
-        })
-        print(summary)
-```
-
-### Trading Operations
-
-```python
-from pdmt5 import Mt5TradingClient
-
-# Create trading client with specific order filling mode
-with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
-    # 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']}")
-
-    # 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"])
-```
-
-## Development
-
-### Setup Development Environment
-
-```bash
-# Clone repository
-git clone https://github.com/dceoy/pdmt5.git
-cd pdmt5
-
-# Install with uv
-uv sync
-
-# Run tests
-uv run pytest test/ -v
-
-# Run type checking
-uv run pyright .
-
-# Run linting
-uv run ruff check --fix .
-uv run ruff format .
-```
-
-### Code Quality
-
-This project maintains high code quality standards:
-
-- **Type Checking**: Strict mode with pyright
-- **Linting**: Comprehensive ruff configuration with 40+ rule categories
-- **Testing**: pytest with coverage tracking (minimum 90%)
-- **Documentation**: Google-style docstrings
-
-## Error Handling
-
-The package provides detailed error information:
-
-```python
-from pdmt5 import Mt5RuntimeError
-
-try:
-    with Mt5DataClient(config=config) as client:
-        data = client.copy_rates_from("INVALID", mt5.TIMEFRAME_H1, datetime.now(), 100)
-except Mt5RuntimeError as e:
-    print(f"MT5 Error: {e}")
-    print(f"Error code: {e.error_code}")
-    print(f"Description: {e.description}")
-```
-
-## Limitations
-
-- **Windows Only**: Due to MetaTrader5 API requirements
-- **MT5 Terminal Required**: The MetaTrader 5 terminal must be installed
-- **Single Thread**: MT5 API is not thread-safe
-
-## Contributing
-
-Contributions are welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Ensure tests pass and coverage is maintained
-4. Submit a pull request
-
-See [CLAUDE.md](CLAUDE.md) for development guidelines.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Author
-
-Daichi Narushima, Ph.D.
-
-## Acknowledgments
-
-- MetaTrader 5 for providing the Python API
-- The pandas community for the excellent data manipulation tools