mt5cli 0.3.0__tar.gz → 0.4.0__tar.gz

{mt5cli-0.3.0 → mt5cli-0.4.0}/AGENTS.md

@@ -29,9 +29,11 @@ uv sync
 - `mt5cli/`: Main package directory
   - `__init__.py`: Package initialization and exports (`detect_format`, `export_dataframe`)
   - `cli.py`: CLI application with typer-based commands for data export
+  - `utils.py`: Constants, enums, parameter types, parsers, and export utilities
   - `__main__.py`: Entry point for `python -m mt5cli`
 - `tests/`: Comprehensive test suite (pytest-based)
-  - `test_cli.py`: Tests for CLI commands, parameter types, and export functions
+  - `test_cli.py`: Tests for CLI commands and collect-history behavior
+  - `test_utils.py`: Tests for utility constants, parameter types, parsers, and export functions
 - `docs/`: MkDocs documentation with API reference
   - `docs/index.md`: Main documentation
   - `docs/api/`: Auto-generated API documentation for all modules

{mt5cli-0.3.0 → mt5cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Command-line tool for MetaTrader 5
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>

{mt5cli-0.3.0 → mt5cli-0.4.0}/docs/api/index.md

@@ -10,12 +10,22 @@ The mt5cli package consists of the following modules:
 
 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.
+
 ## Architecture Overview
 
 The package follows a simple architecture built on top of pdmt5:
 
-1. **CLI Layer** (`cli.py`): Typer application with subcommands for each data type, custom Click parameter types for datetime/timeframe/tick flags parsing, and format detection/export utilities.
-2. **Data Layer** (via `pdmt5`): Uses `Mt5DataClient` and `Mt5Config` from the pdmt5 package for all MetaTrader 5 data access.
+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. **Utils Layer** (`utils.py`): Constants, enums, custom Click parameter types, parsing helpers, and format detection/export utilities.
+4. **Data Layer** (via `pdmt5`): Uses `Mt5DataClient` and `Mt5Config` from the pdmt5 package for all MetaTrader 5 data access.
 
 ## Usage Guidelines
 
@@ -47,15 +57,38 @@ mt5cli -o data.db --table symbols symbols --group "*USD*"
 ## Python API
 
 ```python
-from mt5cli import detect_format, export_dataframe
-import pandas as pd
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mt5cli import (
+    Mt5CliClient,
+    collect_history,
+    copy_rates_range,
+    detect_format,
+    export_dataframe,
+)
+
+# 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
-df = pd.DataFrame({"symbol": ["EURUSD"], "bid": [1.1234]})
-export_dataframe(df, Path("output.csv"), "csv")
+export_dataframe(rates, Path("output.csv"), "csv")
+
+# 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

mt5cli-0.4.0/docs/api/sdk.md

@@ -0,0 +1,3 @@
+# SDK Module
+
+::: mt5cli.sdk

mt5cli-0.4.0/docs/api/utils.md

@@ -0,0 +1,3 @@
+# Utils Module
+
+::: mt5cli.utils

{mt5cli-0.3.0 → mt5cli-0.4.0}/docs/index.md

@@ -20,6 +20,44 @@ mt5cli is a CLI application that exports MetaTrader 5 trading data to multiple f
 pip install mt5cli
 ```
 
+## Programmatic usage / SDK usage
+
+mt5cli can be used as a small Python SDK for read-only MetaTrader 5 data collection. SDK functions return pandas DataFrames without writing files. Use `export_dataframe` when you need to persist results.
+
+```python
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mt5cli import Mt5CliClient, collect_history, copy_rates_range, export_dataframe
+
+# One-off fetch with module-level helpers
+rates = copy_rates_range(
+    "EURUSD",
+    timeframe="H1",
+    date_from="2024-01-01",
+    date_to="2024-02-01",
+)
+export_dataframe(rates, Path("rates.csv"), "csv")
+
+# Reuse one MT5 connection for multiple calls
+with Mt5CliClient(login=12345, password="secret", server="Broker-Demo") as client:
+    account = client.account_info()
+    positions = client.positions()
+
+# Bulk SQLite collection (same behavior as the collect-history CLI command)
+collect_history(
+    Path("history.db"),
+    symbols=["EURUSD", "GBPUSD"],
+    date_from=datetime(2024, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+    timeframe="M1",
+    flags="ALL",
+    with_views=True,
+)
+```
+
+Timeframes, tick flags, and ISO 8601 date strings are accepted wherever noted in the SDK API.
+
 ## Quick Start
 
 ```bash
@@ -138,7 +176,9 @@ History orders and deals are fetched per symbol and concatenated, so the symbol
 
 Browse the API documentation for detailed module information:
 
-- [CLI Module](api/cli.md) - CLI application with export commands and utility functions
+- [CLI Module](api/cli.md) - CLI application with export commands
+- [SDK Module](api/sdk.md) - Programmatic read-only data collection API
+- [Utils Module](api/utils.md) - Constants, parameter types, parsers, and export utilities
 
 ## Development
 

{mt5cli-0.3.0 → mt5cli-0.4.0}/mkdocs.yml

@@ -56,6 +56,8 @@ nav:
   - API Reference:
       - Overview: api/index.md
       - CLI: api/cli.md
+      - SDK: api/sdk.md
+      - Utils: api/utils.md
 
 markdown_extensions:
   - admonition

mt5cli-0.4.0/mt5cli/__init__.py

@@ -0,0 +1,56 @@
+"""mt5cli: Command-line tool and SDK for MetaTrader 5."""
+
+from importlib.metadata import version
+
+from .sdk import (
+    Mt5CliClient,
+    account_info,
+    build_config,
+    collect_history,
+    copy_rates_from,
+    copy_rates_from_pos,
+    copy_rates_range,
+    copy_ticks_from,
+    copy_ticks_range,
+    history_deals,
+    history_orders,
+    last_error,
+    market_book,
+    orders,
+    positions,
+    symbol_info,
+    symbol_info_tick,
+    symbols,
+    terminal_info,
+)
+from .sdk import (
+    version as mt5_version,
+)
+from .utils import detect_format, export_dataframe
+
+__version__ = version(__package__) if __package__ else None
+
+__all__ = [
+    "Mt5CliClient",
+    "account_info",
+    "build_config",
+    "collect_history",
+    "copy_rates_from",
+    "copy_rates_from_pos",
+    "copy_rates_range",
+    "copy_ticks_from",
+    "copy_ticks_range",
+    "detect_format",
+    "export_dataframe",
+    "history_deals",
+    "history_orders",
+    "last_error",
+    "market_book",
+    "mt5_version",
+    "orders",
+    "positions",
+    "symbol_info",
+    "symbol_info_tick",
+    "symbols",
+    "terminal_info",
+]