pdmt5 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

pdmt5/trading.py

@@ -2,13 +2,17 @@
 
 from __future__ import annotations
 
-from typing import Any, Literal
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any, Literal
 
 from pydantic import ConfigDict, Field
 
 from .dataframe import Mt5DataClient
 from .mt5 import Mt5RuntimeError
 
+if TYPE_CHECKING:
+    import pandas as pd
+
 
 class Mt5TradingError(Mt5RuntimeError):
     """MetaTrader5 trading error."""
@@ -190,3 +194,178 @@ class Mt5TradingClient(Mt5DataClient):
                 f"Failed to calculate minimum order margins for symbol: {symbol}."
             )
             raise Mt5TradingError(error_message)
+
+    def calculate_spread_ratio(
+        self,
+        symbol: str,
+    ) -> float:
+        """Calculate the spread ratio for a given symbol.
+
+        Args:
+            symbol: Symbol for which to calculate the spread ratio.
+
+        Returns:
+            Spread ratio as a float.
+        """
+        symbol_info_tick = self.symbol_info_tick_as_dict(symbol=symbol)
+        return (
+            (symbol_info_tick["ask"] - symbol_info_tick["bid"])
+            / (symbol_info_tick["ask"] + symbol_info_tick["bid"])
+            * 2
+        )
+
+    def fetch_latest_rates_as_df(
+        self,
+        symbol: str,
+        granularity: str = "M1",
+        count: int = 1440,
+        index_keys: str | None = "time",
+    ) -> pd.DataFrame:
+        """Fetch rate (OHLC) data as a DataFrame.
+
+        Args:
+            symbol: Symbol to fetch data for.
+            granularity: Time granularity as a timeframe suffix (e.g., "M1", "H1").
+            count: Number of bars to fetch.
+            index_keys: Optional index keys for the DataFrame.
+
+        Returns:
+            pd.DataFrame: OHLC data with time index.
+
+        Raises:
+            Mt5TradingError: If the granularity is not supported by MetaTrader5.
+        """
+        try:
+            timeframe = getattr(self.mt5, f"TIMEFRAME_{granularity.upper()}")
+        except AttributeError as e:
+            error_message = (
+                f"MetaTrader5 does not support the given granularity: {granularity}"
+            )
+            raise Mt5TradingError(error_message) from e
+        else:
+            return self.copy_rates_from_pos_as_df(
+                symbol=symbol,
+                timeframe=timeframe,
+                start_pos=0,
+                count=count,
+                index_keys=index_keys,
+            )
+
+    def fetch_latest_ticks_as_df(
+        self,
+        symbol: str,
+        seconds: int = 300,
+        index_keys: str | None = "time_msc",
+    ) -> pd.DataFrame:
+        """Fetch tick data as a DataFrame.
+
+        Args:
+            symbol: Symbol to fetch tick data for.
+            seconds: Time range in seconds to fetch ticks around the last tick time.
+            index_keys: Optional index keys for the DataFrame.
+
+        Returns:
+            pd.DataFrame: Tick data with time index.
+        """
+        last_tick_time = self.symbol_info_tick_as_dict(symbol=symbol)["time"]
+        return self.copy_ticks_range_as_df(
+            symbol=symbol,
+            date_from=(last_tick_time - timedelta(seconds=seconds)),
+            date_to=(last_tick_time + timedelta(seconds=seconds)),
+            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"])
+            )

{pdmt5-0.1.2.dist-info → pdmt5-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdmt5
-Version: 0.1.2
+Version: 0.1.4
 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,6 +29,7 @@ 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
 
@@ -78,14 +79,13 @@ config = Mt5Config(
     login=12345678,
     password="your_password",
     server="YourBroker-Server",
-    timeout=60000,
-    portable=False
+    timeout=60000
 )
 
 # Use as context manager
 with Mt5DataClient(config=config) as client:
     # Get account information as DataFrame
-    account_info = client.get_account_info_as_df()
+    account_info = client.account_info_as_df()
     print(account_info)
 
     # Get OHLCV data as DataFrame
@@ -98,7 +98,7 @@ with Mt5DataClient(config=config) as client:
     print(rates.head())
 
     # Get current positions as DataFrame
-    positions = client.get_positions_as_df()
+    positions = client.positions_get_as_df()
     print(positions)
 ```
 
@@ -106,34 +106,110 @@ with Mt5DataClient(config=config) as client:
 
 ### 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
+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 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()`
+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 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
+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)
+  - `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
+  - `calculate_spread_ratio()` - Calculate normalized bid-ask spread ratio
+- **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
 
@@ -144,8 +220,7 @@ 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
+    timeout=60000           # Connection timeout in ms
 )
 ```
 
@@ -194,7 +269,7 @@ with Mt5DataClient(config=config) as client:
 ```python
 with Mt5DataClient(config=config) as client:
     # Get all open positions as DataFrame
-    positions = client.get_positions_as_df()
+    positions = client.positions_get_as_df()
 
     if not positions.empty:
         # Calculate summary statistics
@@ -227,6 +302,50 @@ with Mt5TradingClient(config=config, order_filling_mode="IOC") as trader:
         test_results = trader_dry.close_open_positions(symbols=["EURUSD", "GBPUSD"])
 ```
 
+### 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

{pdmt5-0.1.2.dist-info → pdmt5-0.1.4.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=aa4eqRl-xrYqMTdgKgdLJuvg2GIoziE5wA3SRPn0jMs,7377
+pdmt5/trading.py,sha256=qZFORyBlSQNp_DQPeuEIqFHPAnVrCJK_6GhFRc5vDR8,13683
 pdmt5/utils.py,sha256=Ll5Q3OE5h1A_sZ_qVEnOPGniFlT6_MmHfuu0zqeLdeU,3913
-pdmt5-0.1.2.dist-info/METADATA,sha256=0PTSBNZFHetz9WJZLndgNGUSoxFNXFy18rpNJZK05s4,9029
-pdmt5-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pdmt5-0.1.2.dist-info/licenses/LICENSE,sha256=iABrdaUGOBWLYotFupB_PGe8arV5o7rVhn-_vK6P704,1073
-pdmt5-0.1.2.dist-info/RECORD,,
+pdmt5-0.1.4.dist-info/METADATA,sha256=XFIW5O6a7bePMxnDVc7MG6mnkXwNTY_53_mVb_BJxnY,14678
+pdmt5-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pdmt5-0.1.4.dist-info/licenses/LICENSE,sha256=iABrdaUGOBWLYotFupB_PGe8arV5o7rVhn-_vK6P704,1073
+pdmt5-0.1.4.dist-info/RECORD,,