pdmt5 0.0.6__tar.gz → 0.0.8__tar.gz

{pdmt5-0.0.6 → pdmt5-0.0.8}/CLAUDE.md

@@ -63,11 +63,13 @@ uv run mkdocs gh-deploy
 ### Package Structure
 
 - `pdmt5/`: Main package directory
-  - `__init__.py`: Package initialization and exports (Mt5Client, Mt5Config, Mt5DataClient, Mt5RuntimeError)
+  - `__init__.py`: Package initialization and exports (Mt5Client, Mt5Config, Mt5DataClient, Mt5RuntimeError, Mt5TradingClient)
   - `mt5.py`: MT5 terminal client with context manager support (`Mt5Client`, `Mt5RuntimeError`)
   - `dataframe.py`: MT5 data client with pandas DataFrame conversion (`Mt5Config`, `Mt5DataClient`)
+  - `trading.py`: Trading operations client (`Mt5TradingClient`, `Mt5TradingError`)
+  - `utils.py`: Utility decorators and functions for time conversion and DataFrame indexing
 - `test/`: Comprehensive test suite (pytest-based)
-  - `test_init.py`, `test_mt5.py`, `test_dataframe.py`
+  - `test_init.py`, `test_mt5.py`, `test_dataframe.py`, `test_trading.py`, `test_utils.py`
 - `docs/`: MkDocs documentation with API reference
   - `docs/api/`: Auto-generated API documentation for all modules
 - Modern Python packaging with `pyproject.toml` and uv dependency management
@@ -99,6 +101,8 @@ Uses MkDocs with Material theme for API documentation built from Google-style do
 - `docs/api/`: Auto-generated API reference
   - `mt5.md`: Mt5Client and Mt5RuntimeError
   - `dataframe.md`: Mt5Config and Mt5DataClient
+  - `trading.md`: Mt5TradingClient and Mt5TradingError
+  - `utils.md`: Utility decorators and helper functions
 
 ### Workflow
 

{pdmt5-0.0.6 → pdmt5-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdmt5
-Version: 0.0.6
+Version: 0.0.8
 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>
@@ -84,12 +84,12 @@ config = Mt5Config(
 
 # Use as context manager
 with Mt5DataClient(config=config) as client:
-    # Get account information
-    account_info = client.get_account_info()
+    # Get account information as DataFrame
+    account_info = client.get_account_info_as_df()
     print(account_info)
 
-    # Get OHLCV data
-    rates = client.copy_rates_from(
+    # Get OHLCV data as DataFrame
+    rates = client.copy_rates_from_as_df(
         symbol="EURUSD",
         timeframe=mt5.TIMEFRAME_H1,
         date_from=datetime(2024, 1, 1),
@@ -97,17 +97,29 @@ with Mt5DataClient(config=config) as client:
     )
     print(rates.head())
 
-    # Get current positions
-    positions = client.get_positions()
+    # 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
 
-The main interface for interacting with MetaTrader 5:
+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
@@ -116,7 +128,7 @@ The main interface for interacting with MetaTrader 5:
 
 ### Mt5TradingClient
 
-An advanced trading operations interface that extends Mt5DataClient:
+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
@@ -146,8 +158,8 @@ import MetaTrader5 as mt5
 from datetime import datetime
 
 with Mt5DataClient(config=config) as client:
-    # Get last 1000 H1 bars for EURUSD
-    df = client.copy_rates_from(
+    # 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(),
@@ -162,9 +174,11 @@ with Mt5DataClient(config=config) as client:
 ### Working with Tick Data
 
 ```python
+from datetime import datetime, timedelta
+
 with Mt5DataClient(config=config) as client:
-    # Get ticks for the last hour
-    ticks = client.copy_ticks_from(
+    # 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,
@@ -179,8 +193,8 @@ with Mt5DataClient(config=config) as client:
 
 ```python
 with Mt5DataClient(config=config) as client:
-    # Get all open positions
-    positions = client.get_positions()
+    # Get all open positions as DataFrame
+    positions = client.get_positions_as_df()
 
     if not positions.empty:
         # Calculate summary statistics

{pdmt5-0.0.6 → pdmt5-0.0.8}/README.md

@@ -61,12 +61,12 @@ config = Mt5Config(
 
 # Use as context manager
 with Mt5DataClient(config=config) as client:
-    # Get account information
-    account_info = client.get_account_info()
+    # Get account information as DataFrame
+    account_info = client.get_account_info_as_df()
     print(account_info)
 
-    # Get OHLCV data
-    rates = client.copy_rates_from(
+    # Get OHLCV data as DataFrame
+    rates = client.copy_rates_from_as_df(
         symbol="EURUSD",
         timeframe=mt5.TIMEFRAME_H1,
         date_from=datetime(2024, 1, 1),
@@ -74,17 +74,29 @@ with Mt5DataClient(config=config) as client:
     )
     print(rates.head())
 
-    # Get current positions
-    positions = client.get_positions()
+    # 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
 
-The main interface for interacting with MetaTrader 5:
+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
@@ -93,7 +105,7 @@ The main interface for interacting with MetaTrader 5:
 
 ### Mt5TradingClient
 
-An advanced trading operations interface that extends Mt5DataClient:
+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
@@ -123,8 +135,8 @@ import MetaTrader5 as mt5
 from datetime import datetime
 
 with Mt5DataClient(config=config) as client:
-    # Get last 1000 H1 bars for EURUSD
-    df = client.copy_rates_from(
+    # 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(),
@@ -139,9 +151,11 @@ with Mt5DataClient(config=config) as client:
 ### Working with Tick Data
 
 ```python
+from datetime import datetime, timedelta
+
 with Mt5DataClient(config=config) as client:
-    # Get ticks for the last hour
-    ticks = client.copy_ticks_from(
+    # 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,
@@ -156,8 +170,8 @@ with Mt5DataClient(config=config) as client:
 
 ```python
 with Mt5DataClient(config=config) as client:
-    # Get all open positions
-    positions = client.get_positions()
+    # Get all open positions as DataFrame
+    positions = client.get_positions_as_df()
 
     if not positions.empty:
         # Calculate summary statistics

{pdmt5-0.0.6 → pdmt5-0.0.8}/docs/api/trading.md

@@ -34,16 +34,18 @@ from pdmt5 import Mt5TradingClient, Mt5Config
 config = Mt5Config(
     login=123456,
     password="your_password",
-    server="broker_server"
+    server="broker_server",
+    timeout=60000,
+    portable=False
 )
 
 # Create client with dry run mode for testing
-client = Mt5TradingClient(mt5=mt5, config=config, dry_run=True)
+client = Mt5TradingClient(config=config, dry_run=True)
 
 # Use as context manager
 with client:
-    # Get current positions
-    positions_df = client.positions_get_as_df()
+    # Get current positions as DataFrame
+    positions_df = client.get_positions_as_df()
     print(f"Open positions: {len(positions_df)}")
     
     # Close positions for specific symbol
@@ -55,7 +57,7 @@ with client:
 
 ```python
 # Create client for live trading (dry_run=False)
-client = Mt5TradingClient(mt5=mt5, config=config, dry_run=False)
+client = Mt5TradingClient(config=config, dry_run=False)
 
 with client:
     # Close all positions for multiple symbols
@@ -71,21 +73,18 @@ with client:
 # Configure different order filling modes
 # IOC (Immediate or Cancel) - default
 client_ioc = Mt5TradingClient(
-    mt5=mt5, 
     config=config, 
     order_filling_mode="IOC"
 )
 
 # FOK (Fill or Kill)
 client_fok = Mt5TradingClient(
-    mt5=mt5, 
     config=config, 
     order_filling_mode="FOK"
 )
 
 # RETURN (Return if not filled)
 client_return = Mt5TradingClient(
-    mt5=mt5, 
     config=config, 
     order_filling_mode="RETURN"
 )
@@ -120,19 +119,14 @@ except Mt5TradingError as e:
 
 ```python
 with client:
-    # Send or check order depending on dry_run mode
-    request = {
-        "action": mt5.TRADE_ACTION_DEAL,
-        "symbol": "EURUSD",
-        "volume": 1.0,
-        "type": mt5.ORDER_TYPE_BUY,
-        "type_filling": mt5.ORDER_FILLING_IOC,
-        "type_time": mt5.ORDER_TIME_GTC
-    }
+    # Check order (note: send_or_check_order is an internal method)
+    # For trading operations, use the provided methods like close_open_positions
     
-    # In dry_run mode: validates order
-    # In production: sends actual order
-    result = client.send_or_check_order(request)
+    # Example: Check if we can close a position
+    positions = client.get_positions_as_df()
+    if not positions.empty:
+        # Close specific position
+        results = client.close_open_positions("EURUSD")
 ```
 
 ## Position Management Features
@@ -151,10 +145,10 @@ Dry run mode is essential for testing trading strategies:
 
 ```python
 # Test mode - validates orders without execution
-test_client = Mt5TradingClient(mt5=mt5, config=config, dry_run=True)
+test_client = Mt5TradingClient(config=config, dry_run=True)
 
 # Production mode - executes real orders
-prod_client = Mt5TradingClient(mt5=mt5, config=config, dry_run=False)
+prod_client = Mt5TradingClient(config=config, dry_run=False)
 ```
 
 In dry run mode:
@@ -207,9 +201,9 @@ The `close_open_positions()` method returns a dictionary with symbols as keys:
 Since Mt5TradingClient inherits from Mt5DataClient, all data retrieval methods are available:
 
 ```python
-with Mt5TradingClient(mt5=mt5, config=config) as client:
+with Mt5TradingClient(config=config) as client:
     # Get current positions as DataFrame
-    positions_df = client.positions_get_as_df()
+    positions_df = client.get_positions_as_df()
     
     # Analyze positions
     if not positions_df.empty:

{pdmt5-0.0.6 → pdmt5-0.0.8}/docs/api/utils.md

@@ -68,7 +68,7 @@ These utilities enable Mt5DataClient to provide user-friendly data:
 
 ```python
 # Time values are automatically converted
-df = client.symbols_get_as_df(convert_time=True)
+df = client.get_symbols_as_df(convert_time=True)
 # Returns DataFrame with datetime objects instead of Unix timestamps
 
 # DataFrames can have custom indexes

{pdmt5-0.0.6 → pdmt5-0.0.8}/docs/index.md

@@ -19,7 +19,7 @@ pdmt5 is a Python library that provides a pandas-based interface for handling Me
 pip install pdmt5
 ```
 
-## Quick Start
+### Quick Start
 
 ```python
 from pdmt5 import Mt5Client, Mt5Config, Mt5DataClient, Mt5TradingClient
@@ -27,24 +27,37 @@ import MetaTrader5 as mt5
 from datetime import datetime
 
 # Configure connection
-config = Mt5Config(login=12345, password="pass", server="MetaQuotes-Demo")
+config = Mt5Config(
+    login=12345678,
+    password="your_password",
+    server="YourBroker-Server",
+    timeout=60000,
+    portable=False
+)
 
 # Low-level API access with context manager
-with Mt5Client(mt5=mt5) as client:
+with Mt5Client() as client:
     client.initialize()
+    client.login(config.login, config.password, config.server)
     account = client.account_info()
     rates = client.copy_rates_from("EURUSD", mt5.TIMEFRAME_H1, datetime.now(), 100)
 
 # Pandas-friendly interface with automatic initialization
-with Mt5DataClient(mt5=mt5, config=config) as client:
-    symbols_df = client.symbols_get()
-    rates_df = client.copy_rates_from("EURUSD", mt5.TIMEFRAME_H1, datetime.now(), 100)
+with Mt5DataClient(config=config) as client:
+    # Get symbol information as DataFrame
+    symbols_df = client.get_symbols_as_df()
+    # Get OHLCV data as DataFrame
+    rates_df = client.copy_rates_from_as_df(
+        "EURUSD", mt5.TIMEFRAME_H1, datetime.now(), 100
+    )
+    # Get account info as DataFrame
+    account_df = client.get_account_info_as_df()
 
 # Trading operations with dry run support
-with Mt5TradingClient(mt5=mt5, config=config, dry_run=True) as client:
-    # Check open positions
-    positions_df = client.positions_get_as_df()
-    # Close positions for specific symbol
+with Mt5TradingClient(config=config, dry_run=True) as client:
+    # Check open positions as DataFrame
+    positions_df = client.get_positions_as_df()
+    # Close positions for specific symbol (dry run)
     results = client.close_open_positions("EURUSD")
 ```
 
@@ -58,9 +71,10 @@ with Mt5TradingClient(mt5=mt5, config=config, dry_run=True) as client:
 
 Browse the API documentation to learn about available modules and functions:
 
-- [Mt5Client](api/mt5.md) - Base client for low-level MT5 API access and error handling
-- [Mt5DataClient & Mt5Config](api/dataframe.md) - Pandas-friendly data client and configuration
+- [Mt5Client](api/mt5.md) - Base client for low-level MT5 API access with context manager support
+- [Mt5DataClient & Mt5Config](api/dataframe.md) - Pandas-friendly data client with DataFrame conversions
 - [Mt5TradingClient](api/trading.md) - Advanced trading operations with position management
+- [Utility Functions](api/utils.md) - Helper decorators and functions for data processing
 
 ## Development
 

{pdmt5-0.0.6 → pdmt5-0.0.8}/pdmt5/__init__.py

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