pdmt5 0.1.2__tar.gz → 0.1.4__tar.gz

{pdmt5-0.1.2 → pdmt5-0.1.4}/PKG-INFO

@@ -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.4/README.md

@@ -0,0 +1,402 @@
+# 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)
+[![Version](https://img.shields.io/badge/version-0.1.4-green.svg)](https://github.com/dceoy/pdmt5)
+
+## 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)
+  - `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
+
+```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:
+    # 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"])
+```
+
+### 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