mt5cli 0.9.7__tar.gz → 1.0.1__tar.gz

{mt5cli-0.9.7 → mt5cli-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 0.9.7
+Version: 1.0.1
 Summary: Generic MT5 data and execution infrastructure for Python applications
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Office/Business :: Financial :: Investment
 Requires-Python: <3.14,>=3.11
 Requires-Dist: click>=8.1.0
-Requires-Dist: pdmt5>=0.3.0
+Requires-Dist: pdmt5>=1.0.0
 Requires-Dist: typer>=0.15.0
 Provides-Extra: parquet
 Requires-Dist: pyarrow>=19.0.0; extra == 'parquet'
@@ -69,16 +69,14 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 from mt5cli import (
-    DataKind,
-    Dataset,
     MT5Client,
     build_config,
     collect_history,
-    export_dataframe,
     mt5_session,
-    normalize_dataframe,
     update_history_with_config,
 )
+from mt5cli.schemas import DataKind, normalize_dataframe
+from mt5cli.utils import Dataset, export_dataframe
 
 # Persistent session for multiple calls
 with mt5_session(build_config(login=12345, server="Broker-Demo")) as client:
@@ -114,7 +112,7 @@ update_history_with_config(
 )
 ```
 
-Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Storage helpers are re-exported from `mt5cli.storage` and the package root.
+Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Export and storage helpers are in `mt5cli.utils` (`Dataset`, `export_dataframe`) and `mt5cli.history`.
 
 `MT5Client.order_send()` is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly.
 
@@ -237,7 +235,8 @@ For automated pipelines, use the importable incremental API instead of re-fetchi
 
 ```python
 from pdmt5 import Mt5Config, Mt5DataClient
-from mt5cli import Dataset, update_history, update_history_with_config
+from mt5cli import update_history, update_history_with_config
+from mt5cli.utils import Dataset
 
 # Reuse an already-connected pdmt5 client (does not open/close MT5)
 client = Mt5DataClient(config=Mt5Config(login=12345))
@@ -272,7 +271,7 @@ update_history_with_config(
 - **Rate view resolution**: use `resolve_rate_view_name()` / `resolve_rate_view_names()` to map symbols and granularities to existing SQLite compatibility views without creating databases. Both accept `None` (or a missing path) and return deterministic default names unless `require_existing=True`.
 - **Rate view loading**: use `load_rate_data()` / `load_rate_data_from_connection()` to load a SQLite rate table or view into a `DatetimeIndex` DataFrame.
 - **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs, `resolve_rate_tables()` to map them to table/view names (pass `require_existing=True` for strict resolution), and `load_rate_series_from_sqlite()` to load them into a mapping keyed by `(symbol, integer timeframe)`. The loader requires existing managed views unless `explicit_tables` is supplied, and rejects duplicate `(symbol, timeframe)` targets.
-- **Multi-account latest rates**: use `collect_latest_rates_for_accounts()` with `AccountSpec` to read the latest bars for several account groups, merged into a `(symbol, integer timeframe)` mapping. For long-running pollers, `collect_latest_rates_for_accounts_with_retries()` adds bounded exponential backoff that retries only `pdmt5.Mt5TradingError` / `pdmt5.Mt5RuntimeError` and re-raises once `retry_count` is exhausted.
+- **Multi-account latest rates**: use `collect_latest_rates_for_accounts()` with `AccountSpec` to read the latest bars for several account groups, merged into a `(symbol, integer timeframe)` mapping. For long-running pollers, `collect_latest_rates_for_accounts_with_retries()` adds bounded exponential backoff that retries only recoverable MT5 errors and re-raises once `retry_count` is exhausted.
 - **Latest closed bars**: use `collect_latest_closed_rates_for_accounts()` when downstream logic must exclude the still-forming current bar. It fetches `count + 1` bars at `start_pos=0`, drops the last row with `drop_forming_rate_bar()`, and validates each series is non-empty. `collect_latest_closed_rates_by_granularity()` returns the same data keyed by `(symbol, granularity_name)` such as `("EURUSD", "M1")`.
 
 ```python
@@ -289,7 +288,7 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 
 - **Credential resolution**: use `resolve_account_spec()` / `resolve_account_specs()` to merge explicit override values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders (via `substitute_env_placeholders()`), raising `ValueError` for missing variables. This keeps secrets out of plan/config files without coupling to any strategy code. For config dicts or nested structures loaded from YAML/TOML, use `substitute_mapping_values(data, keys={"login", "password"})` to expand placeholders only for caller-specified keys — key names are never hard-coded in mt5cli.
 - **Throttled history updates**: use `ThrottledHistoryUpdater` to wrap `update_history()` with a minimum `interval_seconds` between successful runs (monotonic clock). Call `should_update()` / `update(client, symbols)` from an application loop; errors propagate by default, or pass `suppress_errors=True` to swallow recoverable `Mt5*Error`, `sqlite3.Error`, `ValueError`, `OSError`, and MT5 client capability errors for history API methods without advancing the throttle (other `AttributeError` / `TypeError` values always propagate). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.sdk.update_history`.
-- **Trading session helpers**: use `mt5_trading_session()` for a trading-capable `pdmt5.Mt5TradingClient` that initializes/logs in via `Mt5Config.path` and always shuts down safely. Pair with `detect_position_side()`, `calculate_margin_and_volume()`, and `determine_order_limits()` for generic position and sizing utilities. Keep read-only collection on `mt5_session()` / `MT5Client`.
+- **Trading session helpers**: use `mt5_trading_session()` for a trading-capable client that initializes/logs in via `Mt5Config.path` and always shuts down safely. Pair with `detect_position_side()`, `calculate_margin_and_volume()`, and `determine_order_limits()` for generic position and sizing utilities. Keep read-only collection on `mt5_session()` / `MT5Client`.
 - **Granularity-keyed rate loading**: `load_rate_series_by_granularity()` builds targets with `build_rate_targets()`, loads them with `load_rate_series_from_sqlite()`, and returns a mapping keyed by `(symbol | None, granularity_name)` such as `("EURUSD", "M1")` to reduce downstream boilerplate.
 - **MT5 session helper**: use the `mt5_session()` context manager to attach to (or, when `Mt5Config.path` is set, launch) an MT5 terminal, log in, and yield a connected `MT5Client` that shuts down on exit.
 - **SQLite export helpers**: use `export_dataframe_to_sqlite()` for append mode, optional index export, and post-write deduplication by key columns.

{mt5cli-0.9.7 → mt5cli-1.0.1}/README.md

@@ -44,16 +44,14 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 from mt5cli import (
-    DataKind,
-    Dataset,
     MT5Client,
     build_config,
     collect_history,
-    export_dataframe,
     mt5_session,
-    normalize_dataframe,
     update_history_with_config,
 )
+from mt5cli.schemas import DataKind, normalize_dataframe
+from mt5cli.utils import Dataset, export_dataframe
 
 # Persistent session for multiple calls
 with mt5_session(build_config(login=12345, server="Broker-Demo")) as client:
@@ -89,7 +87,7 @@ update_history_with_config(
 )
 ```
 
-Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Storage helpers are re-exported from `mt5cli.storage` and the package root.
+Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Export and storage helpers are in `mt5cli.utils` (`Dataset`, `export_dataframe`) and `mt5cli.history`.
 
 `MT5Client.order_send()` is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly.
 
@@ -212,7 +210,8 @@ For automated pipelines, use the importable incremental API instead of re-fetchi
 
 ```python
 from pdmt5 import Mt5Config, Mt5DataClient
-from mt5cli import Dataset, update_history, update_history_with_config
+from mt5cli import update_history, update_history_with_config
+from mt5cli.utils import Dataset
 
 # Reuse an already-connected pdmt5 client (does not open/close MT5)
 client = Mt5DataClient(config=Mt5Config(login=12345))
@@ -247,7 +246,7 @@ update_history_with_config(
 - **Rate view resolution**: use `resolve_rate_view_name()` / `resolve_rate_view_names()` to map symbols and granularities to existing SQLite compatibility views without creating databases. Both accept `None` (or a missing path) and return deterministic default names unless `require_existing=True`.
 - **Rate view loading**: use `load_rate_data()` / `load_rate_data_from_connection()` to load a SQLite rate table or view into a `DatetimeIndex` DataFrame.
 - **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs, `resolve_rate_tables()` to map them to table/view names (pass `require_existing=True` for strict resolution), and `load_rate_series_from_sqlite()` to load them into a mapping keyed by `(symbol, integer timeframe)`. The loader requires existing managed views unless `explicit_tables` is supplied, and rejects duplicate `(symbol, timeframe)` targets.
-- **Multi-account latest rates**: use `collect_latest_rates_for_accounts()` with `AccountSpec` to read the latest bars for several account groups, merged into a `(symbol, integer timeframe)` mapping. For long-running pollers, `collect_latest_rates_for_accounts_with_retries()` adds bounded exponential backoff that retries only `pdmt5.Mt5TradingError` / `pdmt5.Mt5RuntimeError` and re-raises once `retry_count` is exhausted.
+- **Multi-account latest rates**: use `collect_latest_rates_for_accounts()` with `AccountSpec` to read the latest bars for several account groups, merged into a `(symbol, integer timeframe)` mapping. For long-running pollers, `collect_latest_rates_for_accounts_with_retries()` adds bounded exponential backoff that retries only recoverable MT5 errors and re-raises once `retry_count` is exhausted.
 - **Latest closed bars**: use `collect_latest_closed_rates_for_accounts()` when downstream logic must exclude the still-forming current bar. It fetches `count + 1` bars at `start_pos=0`, drops the last row with `drop_forming_rate_bar()`, and validates each series is non-empty. `collect_latest_closed_rates_by_granularity()` returns the same data keyed by `(symbol, granularity_name)` such as `("EURUSD", "M1")`.
 
 ```python
@@ -264,7 +263,7 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 
 - **Credential resolution**: use `resolve_account_spec()` / `resolve_account_specs()` to merge explicit override values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders (via `substitute_env_placeholders()`), raising `ValueError` for missing variables. This keeps secrets out of plan/config files without coupling to any strategy code. For config dicts or nested structures loaded from YAML/TOML, use `substitute_mapping_values(data, keys={"login", "password"})` to expand placeholders only for caller-specified keys — key names are never hard-coded in mt5cli.
 - **Throttled history updates**: use `ThrottledHistoryUpdater` to wrap `update_history()` with a minimum `interval_seconds` between successful runs (monotonic clock). Call `should_update()` / `update(client, symbols)` from an application loop; errors propagate by default, or pass `suppress_errors=True` to swallow recoverable `Mt5*Error`, `sqlite3.Error`, `ValueError`, `OSError`, and MT5 client capability errors for history API methods without advancing the throttle (other `AttributeError` / `TypeError` values always propagate). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.sdk.update_history`.
-- **Trading session helpers**: use `mt5_trading_session()` for a trading-capable `pdmt5.Mt5TradingClient` that initializes/logs in via `Mt5Config.path` and always shuts down safely. Pair with `detect_position_side()`, `calculate_margin_and_volume()`, and `determine_order_limits()` for generic position and sizing utilities. Keep read-only collection on `mt5_session()` / `MT5Client`.
+- **Trading session helpers**: use `mt5_trading_session()` for a trading-capable client that initializes/logs in via `Mt5Config.path` and always shuts down safely. Pair with `detect_position_side()`, `calculate_margin_and_volume()`, and `determine_order_limits()` for generic position and sizing utilities. Keep read-only collection on `mt5_session()` / `MT5Client`.
 - **Granularity-keyed rate loading**: `load_rate_series_by_granularity()` builds targets with `build_rate_targets()`, loads them with `load_rate_series_from_sqlite()`, and returns a mapping keyed by `(symbol | None, granularity_name)` such as `("EURUSD", "M1")` to reduce downstream boilerplate.
 - **MT5 session helper**: use the `mt5_session()` context manager to attach to (or, when `Mt5Config.path` is set, launch) an MT5 terminal, log in, and yield a connected `MT5Client` that shuts down on exit.
 - **SQLite export helpers**: use `export_dataframe_to_sqlite()` for append mode, optional index export, and post-write deduplication by key columns.

{mt5cli-0.9.7 → mt5cli-1.0.1}/docs/api/history.md

@@ -182,12 +182,14 @@ targets without hard-coding view names:
 from pathlib import Path
 
 from mt5cli import (
-    load_rate_data,
     load_rate_series_by_granularity,
     load_rate_series_from_sqlite,
+)
+from mt5cli.history import (
+    load_rate_data,
     resolve_rate_table_name,
+    resolve_rate_view_name,
 )
-from mt5cli.history import resolve_rate_view_name
 
 view = resolve_rate_view_name(Path("history.db"), "EURUSD", "M1", require_existing=True)
 rates = load_rate_data(Path("history.db"), view, count=1000)

{mt5cli-0.9.7 → mt5cli-1.0.1}/docs/api/index.md

@@ -13,7 +13,6 @@ responsibilities.
 | [Public API Contract](public-contract.md) | Stable downstream SDK exports, CLI boundary, and out-of-scope items       |
 | [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 |
@@ -30,15 +29,14 @@ flowchart TD
     CLI["mt5cli CLI"] --> Client
     Client --> SDK["sdk / pdmt5"]
     Client --> Schemas["schemas"]
-    Storage["storage"] --> History["history SQLite"]
-    Storage --> Utils["utils export"]
+    History["history SQLite"] --> Utils["utils export"]
     SDK --> PDMT5["pdmt5.Mt5DataClient"]
 ```
 
 Downstream packages should depend on the package root exports documented in the
 [Public API Contract](public-contract.md) (`MT5Client`,
-`DataKind`, `normalize_dataframe`, `collect_history`, `load_rate_data`,
-`resolve_rate_view_name`, etc.) rather than private modules.
+`collect_history`, `load_rate_series_from_sqlite`, etc.) rather than private
+modules. Lower-level helpers are accessible directly from their owning 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.
 

{mt5cli-0.9.7 → mt5cli-1.0.1}/docs/api/public-contract.md

@@ -1,29 +1,41 @@
 # Public API Contract
 
-mt5cli is the generic MT5 data and execution infrastructure layer for downstream
-Python applications. The intended dependency direction is:
+mt5cli is the canonical operational trading SDK and CLI/batch layer over pdmt5.
+The intended dependency direction is:
 
 ```text
 downstream app -> mt5cli -> pdmt5 -> MetaTrader 5
 ```
 
-Downstream packages should import from the package root (`from mt5cli import
-...`) and use the public tier sets in `mt5cli.contract` to distinguish API
-stability. CLI commands mirror the same behavior but are not importable Python
-APIs.
+## Responsibility boundary
+
+| Layer          | Owns                                                                                                                                                                               |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **pdmt5**      | MT5 core wrapper; DataFrame/dict conversion; canonical MT5 constants and parsers; direct low-level order primitives                                                                |
+| **mt5cli**     | CLI/batch workflows; SQLite history collection; normalized datasets; closed-bar helpers; small downstream operational SDK; generic broker-facing margin/volume/order orchestration |
+| **downstream** | Strategy logic; signals; risk policy; backtesting; optimization; YAML/application semantics                                                                                        |
 
-## Public API tiers
+Downstream code should import raw pdmt5 types and constants (such as
+`Mt5Config`, `Mt5RuntimeError`, `TIMEFRAME_MAP`, `COPY_TICKS_MAP`) directly
+from `pdmt5` when needed. mt5cli does not serve as a pass-through compatibility
+namespace for pdmt5. mt5cli's trading helpers type their client parameter against
+an internal protocol backed by `pdmt5.Mt5DataClient`; `Mt5TradingClient` is no
+longer required. `Mt5TradingError` is conditionally imported where still present
+in pdmt5, but mt5cli raises `Mt5OperationError` for all trading-related failures.
 
-mt5cli classifies package-root imports by intended downstream use:
+Note: the former `mt5cli` re-export `TICK_FLAG_MAP` corresponds to `COPY_TICKS_MAP`
+in pdmt5 — the name changed, it was not simply moved.
 
-| Tier             | Contract set               | Meaning                                                                                                                                     |
-| ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Stable core      | `STABLE_SDK_EXPORTS`       | Preferred SDK surface for downstream MT5 infrastructure adapters. Changes require a deliberate compatibility path.                          |
-| Secondary public | `SECONDARY_PUBLIC_EXPORTS` | Public helpers for CLI/export/schema integrations and lower-level MT5 wrappers. Importable, but less central to the downstream trading SDK. |
+Downstream packages should import from the package root (`from mt5cli import
+...`). The contract set `STABLE_SDK_EXPORTS` in `mt5cli.contract` enumerates
+every package-root symbol. Lower-level helpers (schema utilities, export
+functions, parser helpers, low-level MT5 wrappers) are available directly from
+their owning modules (`mt5cli.schemas`, `mt5cli.utils`, `mt5cli.converters`,
+`mt5cli.sdk`, etc.) and are not part of the root SDK surface.
 
 ## Stable downstream SDK API
 
-These names are exported from `mt5cli` and covered by the contract in
+These names are exported from `mt5cli` and enumerated in
 `mt5cli.STABLE_SDK_EXPORTS` (defined in `mt5cli.contract`).
 
 ### Session lifecycle and configuration
@@ -33,23 +45,9 @@ These names are exported from `mt5cli` and covered by the contract in
 | `MT5Client`                                     | Read-only data client with optional `order_check` / `order_send`                                                                                                                                                                                                                  |
 | `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields; `login` accepts `int \| str \| None` — numeric strings are coerced to `int`, blank strings are treated as unset, and `${ENV_VAR}` / `$ENV_NAME` placeholders in string parameters are expanded when `allow_whole_dollar_env=True` |
 | `mt5_session`                                   | Context manager: initialize, login, yield client, shutdown                                                                                                                                                                                                                        |
-| `create_trading_client`, `mt5_trading_session`  | Trading-capable `pdmt5.Mt5TradingClient` lifecycle                                                                                                                                                                                                                                |
+| `create_trading_client`, `mt5_trading_session`  | Trading-capable MT5 client lifecycle; returns a client supporting order execution and account management                                                                                                                                                                          |
 | `AccountSpec`                                   | Generic account group: symbols plus optional credentials                                                                                                                                                                                                                          |
 | `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME`                                                                                                                                                                            |
-| `substitute_env_placeholders`                   | Replace `${NAME}` substrings from the environment; opt-in `allow_whole_dollar_env` for whole-value `$NAME`                                                                                                                                                                        |
-| `substitute_mapping_values`                     | Recursively traverse a dict/list/scalar structure and substitute `${ENV_VAR}` placeholders for caller-selected mapping keys only; optionally normalise blank strings to `None` for a separate caller-selected key set; does not hard-code any application-specific key names      |
-
-Credential resolution is generic: any environment variable name may appear inside
-`${...}`. mt5cli does not hard-code application-specific keys such as
-`mt5_login` or `mt5_exe`.
-
-Pass `allow_whole_dollar_env=True` to `substitute_env_placeholders()`,
-`substitute_mapping_values()`, `resolve_account_spec()`, `resolve_account_specs()`,
-and `build_config()` to additionally expand strings whose entire value is a bare
-`$ENV_NAME` identifier.
-Partial strings such as `"plan$pass"`, `"abc$ENV"`, or `"$ENV-suffix"` are
-**never** expanded — only an exact `$IDENTIFIER` whole-string match qualifies.
-Default is `False` to preserve backward compatibility.
 
 ### Closed-bar rate helpers
 
@@ -61,7 +59,7 @@ timestamp normalization in downstream apps.
 | ------------------------------------------------ | ------------------------------------------------------------------------------- |
 | `drop_forming_rate_bar`                          | Remove the last row from chronologically ordered rate data                      |
 | `fetch_latest_closed_rates`                      | Single connected client: fetch `count + 1`, drop forming bar                    |
-| `fetch_latest_closed_rates_for_trading_client`   | Closed bars from an active `Mt5TradingClient` session; returns RangeIndex       |
+| `fetch_latest_closed_rates_for_trading_client`   | Closed bars from an active trading client session; returns RangeIndex           |
 | `fetch_latest_closed_rates_indexed`              | Same as above but returns a UTC `DatetimeIndex` named `"time"` (no time column) |
 | `collect_latest_closed_rates_for_accounts`       | Multi-account closed bars with optional retry wrapper                           |
 | `collect_latest_closed_rates_by_granularity`     | Same data keyed by `(symbol, granularity_name)`                                 |
@@ -69,20 +67,13 @@ timestamp normalization in downstream apps.
 
 ### SQLite history collection and rate loading
 
-| Symbol                                                                                                                        | Role                                                                                         |
-| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `collect_history`                                                                                                             | One-shot date-range export into SQLite                                                       |
-| `update_history`, `update_history_with_config`                                                                                | Incremental append from `MAX(time)` cursors                                                  |
-| `ThrottledHistoryUpdater`                                                                                                     | Minimum interval between successful incremental updates; optional `update_backend` injection |
-| `resolve_history_datasets`, `resolve_history_timeframes`, `resolve_history_tick_flags`                                        | History pipeline configuration                                                               |
-| `build_rate_view_name`, `resolve_rate_table_name`, `resolve_rate_view_name`, `resolve_rate_view_names`, `resolve_rate_tables` | Map symbols/timeframes to mt5cli-managed table or view names                                 |
-| `RateTarget`, `build_rate_targets`                                                                                            | Neutral `(symbol, timeframe)` series descriptors                                             |
-| `load_rate_data`, `load_rate_data_from_connection`                                                                            | Load one table/view into a time-indexed DataFrame                                            |
-| `load_rate_series_from_sqlite`, `load_rate_series_by_granularity`                                                             | Load one or many series; fail clearly when managed views are missing                         |
-
-Pass `require_existing=True` to rate view resolution helpers when downstream
-code must fail instead of receiving a best-guess view name. Multi-series loaders
-require existing managed `rate_*__*` views unless `explicit_tables` is supplied.
+| Symbol                                                            | Role                                                                                         |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `collect_history`                                                 | One-shot date-range export into SQLite                                                       |
+| `update_history`, `update_history_with_config`                    | Incremental append from `MAX(time)` cursors                                                  |
+| `ThrottledHistoryUpdater`                                         | Minimum interval between successful incremental updates; optional `update_backend` injection |
+| `RateTarget`, `build_rate_targets`                                | Neutral `(symbol, timeframe)` series descriptors                                             |
+| `load_rate_series_from_sqlite`, `load_rate_series_by_granularity` | Load one or many series; fail clearly when managed views are missing                         |
 
 See [History Collection (SQLite)](history.md) for schema, view naming, and ER
 diagrams.
@@ -123,7 +114,7 @@ strategy policy.
 `MT5Client.order_send()` and CLI `order-send --yes` are live execution paths.
 
 Order helpers validate broker stop-level distance in `determine_order_limits()` and
-raise `Mt5TradingError` when computed SL/TP prices are too close to the entry
+raise `Mt5OperationError` when computed SL/TP prices are too close to the entry
 quote. Validation uses `trade_stops_level * point` from the current quote and
 symbol metadata as a pre-check only; it does not guarantee live order acceptance
 after price movement and does not inspect `trade_freeze_level`. Live
@@ -133,51 +124,25 @@ sending requests. Failed, malformed, or unknown broker retcodes are fail-closed
 and returned as `status="failed"` with normalized `request` / `response` details;
 `dry_run=True` never calls `ensure_symbol_selected()` or `order_send()`.
 
-### Errors and MT5 type re-exports
-
-| Symbol                                                                               | Role                                            |
-| ------------------------------------------------------------------------------------ | ----------------------------------------------- |
-| `Mt5CliError`, `Mt5ConnectionError`, `Mt5OperationError`, `Mt5SchemaError`           | Stable mt5cli exception types                   |
-| `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error` | Error normalization and retry classification    |
-| `Mt5Config`, `Mt5RuntimeError`, `Mt5TradingClient`, `Mt5TradingError`                | Re-exported pdmt5 types for adapter convenience |
-
-## Secondary public exports
-
-These names remain importable from `mt5cli` and are covered by
-`SECONDARY_PUBLIC_EXPORTS`, but they are oriented toward CLI/export/schema
-integrations, parsing, and lower-level MT5 access rather than the stable core
-SDK surface. Prefer the stable symbols above for downstream infrastructure
-adapters.
-
-### Read-only MT5 data wrappers
-
-Module-level helpers open a transient connection per call. Prefer `mt5_session`
-or `MT5Client` when making many requests in one process.
+### Errors
 
-| Area                 | Symbols                                                                                              |
-| -------------------- | ---------------------------------------------------------------------------------------------------- |
-| Rates                | `copy_rates_from`, `copy_rates_from_pos`, `copy_rates_range`, `latest_rates`, `collect_latest_rates` |
-| Ticks                | `copy_ticks_from`, `copy_ticks_range`, `recent_ticks`                                                |
-| Account / terminal   | `account_info`, `terminal_info`, `mt5_version`, `last_error`, `mt5_summary`, `mt5_summary_as_df`     |
-| Symbols / market     | `symbols`, `symbol_info`, `symbol_info_tick`, `market_book`, `minimum_margins`                       |
-| Trading state (read) | `orders`, `positions`, `history_orders`, `history_deals`, `recent_history_deals`                     |
-| Multi-account rates  | `collect_latest_rates_for_accounts`                                                                  |
+| Symbol                                                                     | Role                          |
+| -------------------------------------------------------------------------- | ----------------------------- |
+| `Mt5CliError`, `Mt5ConnectionError`, `Mt5OperationError`, `Mt5SchemaError` | Stable mt5cli exception types |
 
-Use `mt5_version` for MetaTrader 5 terminal version data. The name `version` at
-the package root refers to `importlib.metadata.version` (package metadata), not
-the MT5 SDK helper.
+## Module-scoped helpers
 
-### Schema, export, and parser helpers
+Lower-level helpers are available from their owning modules and are not part
+of the package-root stable surface. Import them directly when needed:
 
-| Area                 | Symbols                                                                                                       |
-| -------------------- | ------------------------------------------------------------------------------------------------------------- |
-| Dataset contracts    | `DataKind`, `Dataset`, `IfExists`, `DEDUP_KEYS`, `REQUIRED_COLUMNS`, `TIME_COLUMNS`, `KNOWN_MT5_TIME_COLUMNS` |
-| Schema normalization | `normalize_dataframe`, `normalize_time_columns`, `schema_columns`, `validate_schema`                          |
-| Export helpers       | `detect_format`, `export_dataframe`, `export_dataframe_to_sqlite`                                             |
-| Symbol parsing       | `normalize_symbol`, `normalize_symbols`                                                                       |
-| Time parsing         | `ensure_utc`, `parse_date_range`, `parse_datetime`, `recent_window`                                           |
-| MT5 parsing maps     | `granularity_name`, `parse_tick_flags`, `parse_timeframe`, `TICK_FLAG_MAP`, `TIMEFRAME_MAP`                   |
-| Trading data shapes  | `POSITION_COLUMNS`                                                                                            |
+| Module              | Examples                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| `mt5cli.history`    | `resolve_rate_view_name`, `resolve_rate_tables`, `load_rate_data`, `build_rate_view_name`      |
+| `mt5cli.sdk`        | `copy_rates_from`, `copy_ticks_from`, `account_info`, `symbols`, `mt5_summary`, `latest_rates` |
+| `mt5cli.schemas`    | `DataKind`, `normalize_dataframe`, `validate_schema`, `DEDUP_KEYS`                             |
+| `mt5cli.utils`      | `Dataset`, `IfExists`, `detect_format`, `export_dataframe`, `export_dataframe_to_sqlite`       |
+| `mt5cli.converters` | `normalize_symbol`, `ensure_utc`, `parse_date_range`, `granularity_name`                       |
+| `mt5cli.exceptions` | `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error`           |
 
 ## CLI commands
 
@@ -231,7 +196,7 @@ their own adapter layer.
 
 ## Contract verification
 
-`tests/test_contracts.py` asserts that every name in the stable and secondary
-tier sets is importable from `mt5cli`, documents key closed-bar, rate-view,
-SQLite loading, account-resolution, and trading-session behaviors, and keeps the
-tier sets aligned with `__all__`.
+`tests/test_contracts.py` asserts that every name in `STABLE_SDK_EXPORTS` is
+importable from `mt5cli`, that all package-root exports are covered by the
+stable set, and documents key closed-bar, SQLite loading, account-resolution,
+and trading-session behaviors.

{mt5cli-0.9.7 → mt5cli-1.0.1}/docs/api/sdk.md

@@ -117,7 +117,8 @@ call it every iteration without over-fetching.
 ```python
 from pdmt5 import Mt5Config, Mt5DataClient
 
-from mt5cli import Dataset, ThrottledHistoryUpdater
+from mt5cli import ThrottledHistoryUpdater
+from mt5cli.utils import Dataset
 
 updater = ThrottledHistoryUpdater(
     output="history.db",

{mt5cli-0.9.7 → mt5cli-1.0.1}/docs/api/trading.md

@@ -6,8 +6,9 @@
 
 `create_trading_client()` and `mt5_trading_session()` complement the read-only
 `mt5_session()` helper in `sdk.py`. They return or yield an initialized
-`pdmt5.Mt5TradingClient`, use `Mt5Config.path` to launch the terminal when
-configured, and `mt5_trading_session()` always calls `shutdown()` on exit.
+client supporting order execution and account management, use `Mt5Config.path`
+to launch the terminal when configured, and `mt5_trading_session()` always
+calls `shutdown()` on exit.
 
 ```python
 from mt5cli import create_trading_client, mt5_trading_session
@@ -115,19 +116,19 @@ closed = close_open_positions(client, symbols="EURUSD", dry_run=True)
 `detect_position_side()` returns `long` for buy-only exposure, `short` for
 sell-only exposure, and `None` for no positions or mixed long/short exposure.
 `calculate_spread_ratio()` uses `(ask - bid) / ((ask + bid) / 2)` and raises
-`Mt5TradingError` when bid or ask is missing or non-positive.
+`Mt5OperationError` when bid or ask is missing or non-positive.
 `normalize_order_volume()` returns `0.0` for invalid constraints or
 sub-minimum requests; check the result before calling `estimate_order_margin()`,
 which requires a positive finite volume. `calculate_positions_margin()` silently
 skips rows with missing symbols, non-positive volumes, non-finite volumes, or
-unsupported position types, but propagates `Mt5TradingError` from `estimate_order_margin()` when a valid row
+unsupported position types, but propagates `Mt5OperationError` from `estimate_order_margin()` when a valid row
 encounters invalid tick data or margin results from the broker.
 
 SL/TP ratios for `determine_order_limits()` must satisfy `0 <= ratio < 1`; `0`
 omits that level. SL/TP prices are rounded with symbol `digits` metadata when
 available. `determine_order_limits()` pre-validates computed SL/TP prices against
 available `trade_stops_level * point` metadata when present; violations raise
-`Mt5TradingError`. This is a planning helper only: it does not guarantee broker
+`Mt5OperationError`. This is a planning helper only: it does not guarantee broker
 acceptance because live validation can still depend on price movement, bid/ask
 side, freeze levels, and server-side rules, and it does not validate
 `trade_freeze_level`. When symbol metadata cannot be loaded, protective prices

{mt5cli-0.9.7 → mt5cli-1.0.1}/docs/index.md

@@ -42,19 +42,15 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 from mt5cli import (
-    DataKind,
-    Dataset,
     MT5Client,
     build_config,
     collect_history,
-    export_dataframe,
-    load_rate_data,
-    minimum_margins,
     mt5_session,
-    normalize_dataframe,
-    recent_ticks,
-    resolve_rate_view_name,
 )
+from mt5cli.history import load_rate_data, resolve_rate_view_name
+from mt5cli.schemas import DataKind, normalize_dataframe
+from mt5cli.sdk import minimum_margins, recent_ticks
+from mt5cli.utils import Dataset, export_dataframe
 
 # Persistent session for multiple calls
 with mt5_session(build_config(login=12345, server="Broker-Demo")) as client:
@@ -90,7 +86,7 @@ collect_history(
 )
 ```
 
-Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Storage helpers are re-exported from `mt5cli.storage` and the package root.
+Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Export and storage helpers are in `mt5cli.utils` (`Dataset`, `export_dataframe`) and `mt5cli.history`.
 
 `MT5Client.order_send()` is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly (the CLI requires `--yes` for `order-send`).
 
@@ -151,20 +147,32 @@ mt5cli --login 12345 --password mypass --server MyBroker-Demo \
 | `minimum-margins`  | Export minimum-volume margin summary    |
 | `market-book`      | Export market depth (order book)        |
 
-### Trading
+### Trading State
 
-| Command                | Description                                                 |
-| ---------------------- | ----------------------------------------------------------- |
-| `orders`               | Export active orders                                        |
-| `positions`            | Export open positions                                       |
-| `history-orders`       | Export historical orders                                    |
-| `history-deals`        | Export historical deals                                     |
-| `recent-history-deals` | Export historical deals from a trailing window              |
-| `mt5-summary`          | Export terminal/account status summary                      |
-| `order-check`          | Check funds sufficiency for a trade request                 |
-| `order-send`           | Send a trade request to the trade server (`--yes` required) |
+| Command                | Description                                                           |
+| ---------------------- | --------------------------------------------------------------------- |
+| `orders`               | Export active orders                                                  |
+| `positions`            | Export open positions                                                 |
+| `history-orders`       | Export historical orders                                              |
+| `history-deals`        | Export historical deals                                               |
+| `recent-history-deals` | Export historical deals from a trailing window                        |
+| `mt5-summary`          | Export terminal/account status summary                                |
+| `order-check`          | Check funds sufficiency for a trade request (read-only, no `--yes`)   |
 
-Use `order-check` to validate a request payload before running `order-send --yes`.
+### Execution (live / mutating)
+
+These commands send requests to the live trade server and can place or close
+real trades. Both require `--yes` for live execution.
+
+| Command           | Description                                                                                          |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `order-send`      | Send a **raw** trade request directly to MT5 (`--yes` required; expert path — no extra validation)   |
+| `close-positions` | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` to preview) |
+
+Use `order-check` (Trading State) to validate funds before running `order-send --yes`.
+`close-positions` is the safer high-level alternative that builds correct close
+requests automatically. `order-send` is the expert raw path — downstream
+applications should prefer dedicated closing helpers or their own risk controls.
 
 ### Bulk Collection
 
@@ -221,7 +229,7 @@ See the [History schema diagram](api/history.md#entity-relationship-diagram) for
 
 Browse the API documentation for detailed module information:
 
-- [CLI Module](api/cli.md) - CLI application with export commands
+- [CLI Module](api/cli.md) - CLI application with data export and execution commands
 - [SDK Module](api/sdk.md) - Programmatic read-only data collection API
 - [Utils Module](api/utils.md) - Constants, parameter types, parsers, and export utilities
 

{mt5cli-0.9.7 → mt5cli-1.0.1}/mkdocs.yml

@@ -59,7 +59,6 @@ nav:
       - Public API Contract: api/public-contract.md
       - Client: api/client.md
       - Schemas: api/schemas.md
-      - Storage: api/storage.md
       - Converters: api/converters.md
       - Exceptions: api/exceptions.md
       - CLI: api/cli.md