Daichi Narushima
b5e82e71c7
* Add trading session helpers and extend ThrottledHistoryUpdater Introduce mt5cli.trading with mt5_trading_session() for Mt5TradingClient lifecycle management and reusable operational helpers for position-side detection, margin/volume sizing, and protective order price derivation. Extend ThrottledHistoryUpdater to validate inputs before updates and to optionally suppress ValueError, OSError, and missing-method errors without advancing the throttle timestamp. Export the new helpers from mt5cli.__init__, add unit tests with mocked clients, and document migration guidance for downstream projects such as mteor. Co-authored-by: Daichi Narushima <dceoy@users.noreply.github.com> * Narrow ThrottledHistoryUpdater suppress_errors handling (#27) * Narrow ThrottledHistoryUpdater suppress_errors for MT5 capability only Remove broad AttributeError/TypeError handling from recoverable errors. Add _is_mt5_client_capability_error() to detect missing history API methods or non-callable client attributes by message and attribute name. Generic AttributeError/TypeError values always propagate even when suppress_errors=True. Update docs and tests accordingly. Co-authored-by: Daichi Narushima <dceoy@users.noreply.github.com> * Detect non-callable history client methods in suppress_errors Address review feedback: when a history API attribute exists but is not callable, Python raises a generic TypeError. Inspect the traceback for mt5cli.history client call sites so these capability mismatches are still suppressed without matching all TypeError values. Co-authored-by: Daichi Narushima <dceoy@users.noreply.github.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Daichi Narushima <dceoy@users.noreply.github.com> * Address PR review feedback on trading helpers - Resolve history module path once at import time - Only treat non-callable TypeErrors as capability errors at the raise site - Validate SL/TP ratios in determine_order_limits - Add tests for margin_free edge cases, body-raise shutdown, and internal TypeError propagation - Clarify ThrottledHistoryUpdater suppress_errors docs - Split README migration example into trading vs read-only history sessions Co-authored-by: Daichi Narushima <dceoy@users.noreply.github.com> * Tighten protective ratio validation and clamp negative margin_free Add _require_protective_ratio enforcing 0 <= ratio < 1 for SL/TP limits so a ratio of 1.0 cannot produce zero protective prices. Clamp negative margin_free to 0.0 in calculate_margin_and_volume before sizing. Add boundary and negative-margin tests; document constraints in trading API docs. Co-authored-by: Daichi Narushima <dceoy@users.noreply.github.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Daichi Narushima <dceoy@users.noreply.github.com>
126 lines
3.8 KiB
Markdown
126 lines
3.8 KiB
Markdown
# API Reference
|
|
|
|
This section contains the complete API documentation for mt5cli.
|
|
|
|
## Modules
|
|
|
|
The mt5cli package consists of the following modules:
|
|
|
|
### [CLI](cli.md)
|
|
|
|
Command-line interface module providing typer-based commands for exporting MetaTrader 5 data to CSV, JSON, Parquet, and SQLite3 formats.
|
|
|
|
### [Utils](utils.md)
|
|
|
|
Utility module providing constants, enums, Click parameter types, and helper functions for parsing and exporting data.
|
|
|
|
### [SDK](sdk.md)
|
|
|
|
Programmatic SDK for read-only MetaTrader 5 data collection. Returns pandas DataFrames and provides `collect_history` for SQLite bulk collection.
|
|
|
|
### [Trading](trading.md)
|
|
|
|
Trading-capable session management and operational helpers built on `pdmt5.Mt5TradingClient`. Complements the read-only SDK without changing existing `Mt5CliClient` behavior.
|
|
|
|
### [History Collection (SQLite)](history.md)
|
|
|
|
SQLite storage helpers for the `collect-history` command schema, incremental updates, deduplication, indexes, and optional views.
|
|
|
|
## Architecture Overview
|
|
|
|
The package follows a simple architecture built on top of pdmt5:
|
|
|
|
1. **CLI Layer** (`cli.py`): Typer application with subcommands that delegate to the SDK and export results.
|
|
2. **SDK Layer** (`sdk.py`): Read-only data access functions, `Mt5CliClient`, and `collect_history` orchestration.
|
|
3. **Trading Layer** (`trading.py`): Trading-capable sessions and operational helpers on `Mt5TradingClient`.
|
|
4. **Utils Layer** (`utils.py`): Constants, enums, custom Click parameter types, parsing helpers, and format detection/export utilities.
|
|
5. **Data Layer** (via `pdmt5`): Uses `Mt5DataClient`, `Mt5TradingClient`, and `Mt5Config` from the pdmt5 package for MetaTrader 5 access.
|
|
|
|
## Usage Guidelines
|
|
|
|
All modules follow these conventions:
|
|
|
|
- **Type Safety**: All functions include comprehensive type hints
|
|
- **Error Handling**: User-friendly error messages via typer
|
|
- **Documentation**: Google-style docstrings with examples
|
|
- **Validation**: Custom Click parameter types for input validation
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Export account information to CSV
|
|
mt5cli -o account.csv account-info
|
|
|
|
# Export EURUSD H1 rates to Parquet
|
|
mt5cli -o rates.parquet rates-from --symbol EURUSD --timeframe H1 \
|
|
--date-from 2024-01-01 --count 1000
|
|
|
|
# Export ticks to JSON
|
|
mt5cli -o ticks.json ticks-from --symbol EURUSD \
|
|
--date-from 2024-01-01 --count 500 --flags ALL
|
|
|
|
# Export to SQLite3 with custom table name
|
|
mt5cli -o data.db --table symbols symbols --group "*USD*"
|
|
```
|
|
|
|
## Python API
|
|
|
|
```python
|
|
from datetime import UTC, datetime
|
|
from pathlib import Path
|
|
|
|
from mt5cli import (
|
|
Dataset,
|
|
IfExists,
|
|
Mt5CliClient,
|
|
collect_history,
|
|
copy_rates_range,
|
|
detect_format,
|
|
export_dataframe,
|
|
export_dataframe_to_sqlite,
|
|
minimum_margins,
|
|
recent_ticks,
|
|
)
|
|
from mt5cli.history import resolve_rate_view_name
|
|
|
|
# Fetch rates programmatically
|
|
rates = copy_rates_range(
|
|
"EURUSD",
|
|
timeframe="H1",
|
|
date_from="2024-01-01",
|
|
date_to="2024-02-01",
|
|
)
|
|
|
|
# Detect output format from file extension
|
|
fmt = detect_format(Path("output.parquet")) # Returns "parquet"
|
|
|
|
# Export a DataFrame
|
|
export_dataframe(rates, Path("output.csv"), "csv")
|
|
|
|
# Append to SQLite with deduplication
|
|
export_dataframe_to_sqlite(
|
|
rates,
|
|
Path("history.db"),
|
|
"rates",
|
|
if_exists=IfExists.APPEND,
|
|
deduplicate_on=("symbol", "timeframe", "time"),
|
|
)
|
|
|
|
# Resolve rate compatibility views and fetch recent ticks
|
|
view = resolve_rate_view_name(Path("history.db"), "EURUSD", "M1")
|
|
ticks = recent_ticks("EURUSD", seconds=300)
|
|
margins = minimum_margins("EURUSD")
|
|
|
|
# Collect history into SQLite
|
|
collect_history(
|
|
Path("history.db"),
|
|
symbols=["EURUSD"],
|
|
date_from=datetime(2024, 1, 1, tzinfo=UTC),
|
|
date_to=datetime(2024, 2, 1, tzinfo=UTC),
|
|
)
|
|
```
|
|
|
|
## Examples
|
|
|
|
See individual module pages for detailed usage examples and code samples.
|