feat: stable MT5Client public API and infrastructure layer (#30)
* feat: add stable MT5Client public API and infrastructure layer Introduce a reusable public API for downstream trading applications: - MT5Client as the primary client abstraction with order_check/order_send - schemas module with DataKind contracts, validation, and normalization - converters, exceptions, retry, and storage facade modules - CLI order commands now route through MT5Client - connected_client made public; retry logic centralized - Contract tests for API surface, schemas, and storage round-trips - README and docs updated with Python API usage examples Co-authored-by: Daichi Narushima <dceoy@users.noreply.github.com> * fix: correct time coercion, broker-safe symbols, and execution docs - Normalize MT5 time columns with correct second/millisecond units - Coerce all present known MT5 time fields, including optional order times - Preserve broker symbol casing in normalize_symbol() - Document order_send() as a live execution primitive with clear scope boundaries - Add contract tests for timestamp and symbol normalization behavior 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>
This commit is contained in:
Daichi Narushima
+39
-111
@@ -1,125 +1,53 @@
|
||||
# API Reference
|
||||
|
||||
This section contains the complete API documentation for mt5cli.
|
||||
This section documents the mt5cli public Python API and CLI modules.
|
||||
|
||||
## Modules
|
||||
## Public API layers
|
||||
|
||||
The mt5cli package consists of the following modules:
|
||||
| Module | Purpose |
|
||||
| ----------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| [Client](client.md) | `MT5Client` session abstraction for data access and order primitives |
|
||||
| [Schemas](schemas.md) | Canonical DataFrame contracts and normalization helpers |
|
||||
| [Storage](storage.md) | CSV/JSON/Parquet/SQLite export and history collection helpers |
|
||||
| [Converters](converters.md) | Symbol, timeframe, timezone, and date-range utilities |
|
||||
| [Exceptions](exceptions.md) | Stable mt5cli exception types and MT5 error normalization |
|
||||
| [SDK](sdk.md) | Module-level fetch helpers, multi-account collectors, incremental history |
|
||||
| [Trading](trading.md) | Trading-capable sessions and operational helpers |
|
||||
| [History Collection (SQLite)](history.md) | SQLite schema, incremental writes, dedup, and rate views |
|
||||
| [CLI](cli.md) | Typer commands that delegate to the Python API |
|
||||
| [Utils](utils.md) | Parsing helpers and Click parameter types |
|
||||
|
||||
### [CLI](cli.md)
|
||||
## Architecture overview
|
||||
|
||||
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*"
|
||||
```mermaid
|
||||
flowchart TD
|
||||
App["Downstream application"] --> Client["MT5Client"]
|
||||
CLI["mt5cli CLI"] --> Client
|
||||
Client --> SDK["sdk / pdmt5"]
|
||||
Client --> Schemas["schemas"]
|
||||
Storage["storage"] --> History["history SQLite"]
|
||||
Storage --> Utils["utils export"]
|
||||
SDK --> PDMT5["pdmt5.Mt5DataClient"]
|
||||
```
|
||||
|
||||
## Python API
|
||||
Downstream packages should depend on the package root exports (`MT5Client`, `DataKind`, `normalize_dataframe`, `export_dataframe`, `collect_history`, etc.) rather than private modules.
|
||||
|
||||
`MT5Client.order_send()` is a live execution primitive that can place real trades. mt5cli exposes minimal execution helpers only; strategy logic, signals, backtests, and optimization remain out of scope and must be implemented downstream with explicit execution gating.
|
||||
|
||||
## Quick start
|
||||
|
||||
```python
|
||||
from datetime import UTC, datetime
|
||||
from pathlib import Path
|
||||
from mt5cli import MT5Client, build_config, mt5_session
|
||||
|
||||
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),
|
||||
)
|
||||
with mt5_session(build_config(login=12345)) as client:
|
||||
rates = client.copy_rates_range("EURUSD", "H1", "2024-01-01", "2024-02-01")
|
||||
positions = client.positions()
|
||||
```
|
||||
|
||||
## Examples
|
||||
```bash
|
||||
mt5cli -o account.csv account-info
|
||||
mt5cli -o rates.parquet rates-range --symbol EURUSD --timeframe H1 \
|
||||
--date-from 2024-01-01 --date-to 2024-02-01
|
||||
```
|
||||
|
||||
See individual module pages for detailed usage examples and code samples.
|
||||
See individual module pages for detailed usage examples.
|
||||
|
||||
Reference in New Issue
Block a user