mt5cli 1.1.6__tar.gz → 1.2.0__tar.gz

{mt5cli-1.1.6 → mt5cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.1.6
+Version: 1.2.0
 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>
@@ -134,28 +134,17 @@ unset. Pass `allow_whole_dollar_env=True` to expand `${ENV_VAR}` and bare
 from mt5cli import (
     build_config,
     calculate_spread_ratio,
-    create_trading_client,
     get_account_snapshot,
-    mt5_trading_session,
+    mt5_session,
 )
 
 # Login from environment — numeric string is coerced to int automatically
 config = build_config(login="$MT5_LOGIN", allow_whole_dollar_env=True)
 
-with mt5_trading_session(
-    path=r"C:\Program Files\MetaTrader 5\terminal64.exe",
-    login="12345",
-    password="from-env-or-secret-store",
-    server="Broker-Demo",
-) as client:
+with mt5_session(config) as client:
     account = get_account_snapshot(client)
     spread = calculate_spread_ratio(client, "EURUSD")
-
-client = create_trading_client(login=12345, server="Broker-Demo")
-try:
-    positions = client.positions_get_as_df(symbol="EURUSD")
-finally:
-    client.shutdown()
+    positions = client.positions(symbol="EURUSD")
 ```
 
 ## CLI usage
@@ -278,30 +267,19 @@ Appends one timestamped row per data type. Never places orders or modifies tradi
 #### SDK usage
 
 ```python
-from pdmt5 import Mt5DataClient, Mt5Config
-from mt5cli import update_observability, update_observability_with_config
-
-# Reuse an already-connected client
-client = Mt5DataClient(config=Mt5Config(login=12345))
-client.initialize_and_login_mt5()
-try:
-    update_observability(
-        client=client,
-        output="history.db",
-        symbols=["EURUSD", "GBPUSD"],  # optional position/order filter
-        include_account=True,
-        include_positions=True,
-        include_orders=True,
-        include_terminal=True,
-        with_grafana_schema=True,
-    )
-finally:
-    client.shutdown()
+from pdmt5 import Mt5Config
+from mt5cli import update_observability_with_config
 
-# Standalone wrapper that opens/closes MT5 automatically
+# This wrapper owns the MT5 connection automatically.
 update_observability_with_config(
     output="history.db",
     config=Mt5Config(login=12345),
+    symbols=["EURUSD", "GBPUSD"],  # optional position/order filter
+    include_account=True,
+    include_positions=True,
+    include_orders=True,
+    include_terminal=True,
+    with_grafana_schema=True,
 )
 ```
 
@@ -359,33 +337,21 @@ OpenTelemetry metrics are documented in [`docs/api/telemetry.md`](docs/api/telem
 For automated pipelines, use the importable incremental API instead of re-fetching fixed date ranges:
 
 ```python
-from pdmt5 import Mt5Config, Mt5DataClient
-from mt5cli import update_history, update_history_with_config
+from pdmt5 import Mt5Config
+from mt5cli import 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))
-client.initialize_and_login_mt5()
-try:
-    update_history(
-        client=client,
-        output="history.db",
-        symbols=["EURUSD", "GBPUSD"],
-        datasets={Dataset.rates, Dataset.history_deals},
-        timeframes=["M1", "H1"],  # default: all fixed MT5 timeframes
-        lookback_hours=24,
-        create_rate_views=True,
-        with_views=True,
-        include_account_events=True,
-    )
-finally:
-    client.shutdown()
-
-# Standalone wrapper that opens and closes MT5 for you
+# This wrapper opens and closes MT5 for you.
 update_history_with_config(
     output="history.db",
-    symbols=["EURUSD"],
+    symbols=["EURUSD", "GBPUSD"],
     config=Mt5Config(login=12345),
+    datasets={Dataset.rates, Dataset.history_deals},
+    timeframes=["M1", "H1"],  # default: all fixed MT5 timeframes
+    lookback_hours=24,
+    create_rate_views=True,
+    with_views=True,
+    include_account_events=True,
 )
 ```
 
@@ -412,8 +378,8 @@ 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 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`.
+- **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`, and `OSError` without advancing the throttle (`AttributeError` / `TypeError` always propagate, since the client passed to `update()` must implement the canonical `HistoryClient` method names). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.history.update_history`.
+- **Trading helpers**: use `mt5_session()` for both market data and generic execution helpers. It owns initialization and shutdown for sessions it creates; caller-supplied clients remain caller-owned.
 - **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.
@@ -431,7 +397,7 @@ Replace local MT5 lifecycle and trading helper code with mt5cli imports:
 
 ```python
 # Before (local application helpers)
-# with local_mt5_trading_session(config) as client:
+# with local_mt5_session(config) as client:
 #     side = local_detect_position_side(client, symbol)
 #     sizing = local_calculate_margin_and_volume(client, symbol, unit_ratio, preserved_ratio)
 #     limits = local_determine_order_limits(client, symbol, side, sl_ratio, tp_ratio)
@@ -442,12 +408,10 @@ from mt5cli import (
     calculate_margin_and_volume,
     detect_position_side,
     determine_order_limits,
-    mt5_trading_session,
+    mt5_session,
 )
 
-with mt5_trading_session(
-    Mt5Config(path=terminal_path, login=login), retry_count=2
-) as client:
+with mt5_session(Mt5Config(path=terminal_path, login=login)) as client:
     side = detect_position_side(client, symbol)
     sizing = calculate_margin_and_volume(
         client, symbol, unit_margin_ratio=0.5, preserved_margin_ratio=0.2
@@ -465,19 +429,15 @@ with mt5_trading_session(
 Throttled history updates use a separate read-only session:
 
 ```python
-from pdmt5 import Mt5Config, Mt5DataClient
+from pdmt5 import Mt5Config
 
-from mt5cli import ThrottledHistoryUpdater
+from mt5cli import ThrottledHistoryUpdater, mt5_session
 
 updater = ThrottledHistoryUpdater(
     output="history.db", interval_seconds=60, suppress_errors=True
 )
-client = Mt5DataClient(config=Mt5Config(login=login))
-client.initialize_and_login_mt5()
-try:
+with mt5_session(Mt5Config(login=login)) as client:
     updater.update(client, ["EURUSD"])
-finally:
-    client.shutdown()
 ```
 
 Read-only collectors can keep using `mt5_session()` and `MT5Client`.

{mt5cli-1.1.6 → mt5cli-1.2.0}/README.md

@@ -103,28 +103,17 @@ unset. Pass `allow_whole_dollar_env=True` to expand `${ENV_VAR}` and bare
 from mt5cli import (
     build_config,
     calculate_spread_ratio,
-    create_trading_client,
     get_account_snapshot,
-    mt5_trading_session,
+    mt5_session,
 )
 
 # Login from environment — numeric string is coerced to int automatically
 config = build_config(login="$MT5_LOGIN", allow_whole_dollar_env=True)
 
-with mt5_trading_session(
-    path=r"C:\Program Files\MetaTrader 5\terminal64.exe",
-    login="12345",
-    password="from-env-or-secret-store",
-    server="Broker-Demo",
-) as client:
+with mt5_session(config) as client:
     account = get_account_snapshot(client)
     spread = calculate_spread_ratio(client, "EURUSD")
-
-client = create_trading_client(login=12345, server="Broker-Demo")
-try:
-    positions = client.positions_get_as_df(symbol="EURUSD")
-finally:
-    client.shutdown()
+    positions = client.positions(symbol="EURUSD")
 ```
 
 ## CLI usage
@@ -247,30 +236,19 @@ Appends one timestamped row per data type. Never places orders or modifies tradi
 #### SDK usage
 
 ```python
-from pdmt5 import Mt5DataClient, Mt5Config
-from mt5cli import update_observability, update_observability_with_config
-
-# Reuse an already-connected client
-client = Mt5DataClient(config=Mt5Config(login=12345))
-client.initialize_and_login_mt5()
-try:
-    update_observability(
-        client=client,
-        output="history.db",
-        symbols=["EURUSD", "GBPUSD"],  # optional position/order filter
-        include_account=True,
-        include_positions=True,
-        include_orders=True,
-        include_terminal=True,
-        with_grafana_schema=True,
-    )
-finally:
-    client.shutdown()
+from pdmt5 import Mt5Config
+from mt5cli import update_observability_with_config
 
-# Standalone wrapper that opens/closes MT5 automatically
+# This wrapper owns the MT5 connection automatically.
 update_observability_with_config(
     output="history.db",
     config=Mt5Config(login=12345),
+    symbols=["EURUSD", "GBPUSD"],  # optional position/order filter
+    include_account=True,
+    include_positions=True,
+    include_orders=True,
+    include_terminal=True,
+    with_grafana_schema=True,
 )
 ```
 
@@ -328,33 +306,21 @@ OpenTelemetry metrics are documented in [`docs/api/telemetry.md`](docs/api/telem
 For automated pipelines, use the importable incremental API instead of re-fetching fixed date ranges:
 
 ```python
-from pdmt5 import Mt5Config, Mt5DataClient
-from mt5cli import update_history, update_history_with_config
+from pdmt5 import Mt5Config
+from mt5cli import 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))
-client.initialize_and_login_mt5()
-try:
-    update_history(
-        client=client,
-        output="history.db",
-        symbols=["EURUSD", "GBPUSD"],
-        datasets={Dataset.rates, Dataset.history_deals},
-        timeframes=["M1", "H1"],  # default: all fixed MT5 timeframes
-        lookback_hours=24,
-        create_rate_views=True,
-        with_views=True,
-        include_account_events=True,
-    )
-finally:
-    client.shutdown()
-
-# Standalone wrapper that opens and closes MT5 for you
+# This wrapper opens and closes MT5 for you.
 update_history_with_config(
     output="history.db",
-    symbols=["EURUSD"],
+    symbols=["EURUSD", "GBPUSD"],
     config=Mt5Config(login=12345),
+    datasets={Dataset.rates, Dataset.history_deals},
+    timeframes=["M1", "H1"],  # default: all fixed MT5 timeframes
+    lookback_hours=24,
+    create_rate_views=True,
+    with_views=True,
+    include_account_events=True,
 )
 ```
 
@@ -381,8 +347,8 @@ 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 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`.
+- **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`, and `OSError` without advancing the throttle (`AttributeError` / `TypeError` always propagate, since the client passed to `update()` must implement the canonical `HistoryClient` method names). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.history.update_history`.
+- **Trading helpers**: use `mt5_session()` for both market data and generic execution helpers. It owns initialization and shutdown for sessions it creates; caller-supplied clients remain caller-owned.
 - **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.
@@ -400,7 +366,7 @@ Replace local MT5 lifecycle and trading helper code with mt5cli imports:
 
 ```python
 # Before (local application helpers)
-# with local_mt5_trading_session(config) as client:
+# with local_mt5_session(config) as client:
 #     side = local_detect_position_side(client, symbol)
 #     sizing = local_calculate_margin_and_volume(client, symbol, unit_ratio, preserved_ratio)
 #     limits = local_determine_order_limits(client, symbol, side, sl_ratio, tp_ratio)
@@ -411,12 +377,10 @@ from mt5cli import (
     calculate_margin_and_volume,
     detect_position_side,
     determine_order_limits,
-    mt5_trading_session,
+    mt5_session,
 )
 
-with mt5_trading_session(
-    Mt5Config(path=terminal_path, login=login), retry_count=2
-) as client:
+with mt5_session(Mt5Config(path=terminal_path, login=login)) as client:
     side = detect_position_side(client, symbol)
     sizing = calculate_margin_and_volume(
         client, symbol, unit_margin_ratio=0.5, preserved_margin_ratio=0.2
@@ -434,19 +398,15 @@ with mt5_trading_session(
 Throttled history updates use a separate read-only session:
 
 ```python
-from pdmt5 import Mt5Config, Mt5DataClient
+from pdmt5 import Mt5Config
 
-from mt5cli import ThrottledHistoryUpdater
+from mt5cli import ThrottledHistoryUpdater, mt5_session
 
 updater = ThrottledHistoryUpdater(
     output="history.db", interval_seconds=60, suppress_errors=True
 )
-client = Mt5DataClient(config=Mt5Config(login=login))
-client.initialize_and_login_mt5()
-try:
+with mt5_session(Mt5Config(login=login)) as client:
     updater.update(client, ["EURUSD"])
-finally:
-    client.shutdown()
 ```
 
 Read-only collectors can keep using `mt5_session()` and `MT5Client`.

{mt5cli-1.1.6 → mt5cli-1.2.0}/docs/api/history.md

@@ -286,3 +286,61 @@ frame = series["EURUSD", 1]  # keyed by (symbol, integer timeframe)
   )
   frame = series["EURUSD", "M1"]  # keyed by (symbol | None, granularity_name)
   ```
+
+## Throttled incremental history updates
+
+`ThrottledHistoryUpdater` wraps `update_history()` with a minimum interval
+between successful runs (using a monotonic clock), so an application loop can
+call it every iteration without over-fetching.
+
+```python
+from pdmt5 import Mt5Config
+
+from mt5cli import ThrottledHistoryUpdater, mt5_session
+from mt5cli.utils import Dataset
+
+updater = ThrottledHistoryUpdater(
+    output="history.db",
+    datasets={Dataset.rates},
+    timeframes=["M1"],
+    interval_seconds=60,  # <= 0 updates on every call
+)
+
+with mt5_session(Mt5Config(login=12345)) as client:
+    while True:
+        updater.update(client, ["EURUSD", "GBPUSD"])  # no-op until 60s elapse
+        # ... do other work; break when shutting down ...
+```
+
+Pass `update_backend` to substitute the default `update_history` implementation
+without monkey-patching `mt5cli.history.update_history`. The callable receives the
+same keyword arguments as `update_history` (`client`, `output`, `symbols`,
+`datasets`, `timeframes`, `flags`, `lookback_hours`, `with_views`,
+`include_account_events`). The resolved backend is stored on
+`updater.update_backend` for inspection or subclassing.
+
+```python
+from mt5cli import ThrottledHistoryUpdater, update_history
+
+
+def app_update_history(**kwargs) -> None:
+    update_history(**kwargs)  # or delegate to application-specific logic
+
+
+updater = ThrottledHistoryUpdater(
+    output="history.db",
+    interval_seconds=60,
+    update_backend=app_update_history,
+)
+```
+
+By default recoverable errors (`Mt5RuntimeError`, `sqlite3.Error`,
+`ValueError`, `OSError`) propagate so the caller controls logging; pass
+`suppress_errors=True` to swallow them and return `False` without advancing the
+throttle. `AttributeError` and `TypeError` are treated as caller programming
+errors and always propagate, even when `suppress_errors=True` — the client
+passed to `update()` must implement the canonical `HistoryClient` method names
+(`copy_rates_range`, `copy_ticks_range`, `history_orders`, `history_deals`,
+`symbol_info_as_dict`). Input validation (`_resolve_update_history_request`)
+runs before any MT5 or SQLite calls, but when `suppress_errors=True` the
+resulting `ValueError` is suppressed along with other recoverable errors.

{mt5cli-1.1.6 → mt5cli-1.2.0}/docs/api/index.md

@@ -8,31 +8,34 @@ responsibilities.
 
 ## Public API layers
 
-| Module                                    | Purpose                                                                   |
-| ----------------------------------------- | ------------------------------------------------------------------------- |
-| [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                   |
-| [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                  |
-| [Telemetry](telemetry.md)                 | OpenTelemetry metrics setup, meters, and emitted metric names             |
-| [Grafana](grafana.md)                     | Grafana-ready SQLite schema, views, snapshots, and published copies       |
-| [CLI](cli.md)                             | Typer commands that delegate to the Python API                            |
-| [Utils](utils.md)                         | Parsing helpers and Click parameter types                                 |
+| Module                                    | Purpose                                                                              |
+| ----------------------------------------- | ------------------------------------------------------------------------------------ |
+| [Public API Contract](public-contract.md) | Stable downstream SDK exports, CLI boundary, and out-of-scope items                  |
+| [Client](client.md)                       | `MT5Client` / `mt5_session()` — the sole connection lifecycle and client abstraction |
+| [Market Data](marketdata.md)              | Stateless one-off market-data reads and multi-account rate collection                |
+| [Schemas](schemas.md)                     | Canonical DataFrame contracts and normalization helpers                              |
+| [Converters](converters.md)               | Symbol, timeframe, timezone, and date-range utilities                                |
+| [Exceptions](exceptions.md)               | Stable mt5cli exception types and MT5 error normalization                            |
+| [Trading](trading.md)                     | Trading-capable sessions and operational helpers                                     |
+| [History Collection (SQLite)](history.md) | SQLite schema, incremental writes, dedup, and rate views                             |
+| [Observability](observability.md)         | Account/position/order/terminal snapshot orchestration                               |
+| [Telemetry](telemetry.md)                 | OpenTelemetry metrics setup, meters, and emitted metric names                        |
+| [Grafana](grafana.md)                     | Grafana-ready SQLite schema, views, snapshots, and published copies                  |
+| [CLI](cli.md)                             | Typer commands that delegate to the Python API                                       |
+| [Utils](utils.md)                         | Generic parsing, conversion, and export helpers                                      |
 
 ## Architecture overview
 
 ```mermaid
 flowchart TD
-    App["Downstream application"] --> Client["MT5Client"]
+    App["Downstream application"] --> Client["MT5Client / mt5_session"]
     CLI["mt5cli CLI"] --> Client
-    Client --> SDK["sdk / pdmt5"]
-    Client --> Schemas["schemas"]
-    History["history SQLite"] --> Utils["utils export"]
-    SDK --> PDMT5["pdmt5.Mt5DataClient"]
+    Client --> PDMT5["pdmt5.Mt5DataClient"]
+    MarketData["marketdata"] --> Client
+    History["history"] --> Client
+    Observability["observability"] --> Client
+    Observability --> Grafana["grafana"]
+    History --> Utils["utils export"]
 ```
 
 Downstream packages should depend on the package root exports documented in the

mt5cli-1.1.6/docs/api/sdk.md → mt5cli-1.2.0/docs/api/marketdata.md

@@ -1,11 +1,11 @@
-# SDK Module
+# Market Data Module
 
-::: mt5cli.sdk
+::: mt5cli.marketdata
 
 ## Resilient multi-account orchestration
 
-The SDK ships strategy-agnostic helpers for building long-running collectors on
-top of the read-only client. None of them depend on a particular trading
+This module ships strategy-agnostic helpers for building long-running
+collectors on top of `MT5Client`. None of them depend on a particular trading
 application.
 
 ### Retrying transient rate collection
@@ -31,9 +31,8 @@ rates = collect_latest_rates_for_accounts_with_retries(
 ### Latest closed rate bars
 
 MetaTrader 5 `start_pos=0` includes the still-forming current bar as the last
-row. `fetch_latest_closed_rates()` handles one connected `MT5Client`; use
-`fetch_latest_closed_rates_for_trading_client()` from an active trading
-session created by `create_trading_client()`. Multi-account helpers fetch
+row. `fetch_latest_closed_rates()` handles one connected `MT5Client`.
+Multi-account helpers fetch
 `count + 1` bars, drop
 that row with `drop_forming_rate_bar()`, and validate each series is non-empty. Returned frames are ordered
 oldest-to-newest and may contain fewer than `count` rows only when MT5 returns
@@ -109,66 +108,6 @@ resolved = resolve_account_specs(accounts, allow_whole_dollar_env=True)
 # resolved[0].password == "secret"
 ```
 
-### Throttled incremental history updates
-
-`ThrottledHistoryUpdater` wraps `update_history()` with a minimum interval
-between successful runs (using a monotonic clock), so an application loop can
-call it every iteration without over-fetching.
-
-```python
-from pdmt5 import Mt5Config, Mt5DataClient
-
-from mt5cli import ThrottledHistoryUpdater
-from mt5cli.utils import Dataset
-
-updater = ThrottledHistoryUpdater(
-    output="history.db",
-    datasets={Dataset.rates},
-    timeframes=["M1"],
-    interval_seconds=60,  # <= 0 updates on every call
-)
-
-client = Mt5DataClient(config=Mt5Config(login=12345))
-client.initialize_and_login_mt5()
-try:
-    while True:
-        updater.update(client, ["EURUSD", "GBPUSD"])  # no-op until 60s elapse
-        # ... do other work; break when shutting down ...
-finally:
-    client.shutdown()
-```
-
-Pass `update_backend` to substitute the default `update_history` implementation
-without monkey-patching `mt5cli.sdk.update_history`. The callable receives the
-same keyword arguments as `update_history` (`client`, `output`, `symbols`,
-`datasets`, `timeframes`, `flags`, `lookback_hours`, `with_views`,
-`include_account_events`). The resolved backend is stored on
-`updater.update_backend` for inspection or subclassing.
-
-```python
-from mt5cli import ThrottledHistoryUpdater, update_history
-
-
-def app_update_history(**kwargs) -> None:
-    update_history(**kwargs)  # or delegate to application-specific logic
-
-
-updater = ThrottledHistoryUpdater(
-    output="history.db",
-    interval_seconds=60,
-    update_backend=app_update_history,
-)
-```
-
-By default recoverable errors (`Mt5RuntimeError`, `sqlite3.Error`,
-`ValueError`, `OSError`, and MT5 client capability
-`AttributeError` / `TypeError` for history API methods) propagate so the caller
-controls logging; pass `suppress_errors=True` to swallow them and return
-`False` without advancing the throttle. Other `AttributeError` / `TypeError`
-values always propagate. Input validation (`_resolve_update_history_request`)
-runs before any MT5 or SQLite calls, but when `suppress_errors=True` the
-resulting `ValueError` is suppressed along with other recoverable errors.
-
 ## Trading-capable sessions
 
 For order placement and trading calculations, use the dedicated

mt5cli-1.2.0/docs/api/observability.md

@@ -0,0 +1,38 @@
+# Observability Module
+
+::: mt5cli.observability
+
+## Grafana observability (SQLite read model)
+
+These helpers append timestamped account/position/order/terminal snapshot
+rows into a SQLite database, preparing it as a Grafana datasource. All DDL is
+idempotent (`CREATE TABLE IF NOT EXISTS`, `DROP VIEW IF EXISTS` + `CREATE
+VIEW`, `CREATE INDEX IF NOT EXISTS`). Missing source tables are skipped with a
+warning rather than raising an error.
+
+| Symbol                             | Role                                                                                        |
+| ---------------------------------- | ------------------------------------------------------------------------------------------- |
+| `update_observability`             | Append one timestamped snapshot row per data type from a connected client implementation    |
+| `update_observability_with_config` | Standalone wrapper: opens/closes MT5 connection automatically around `update_observability` |
+
+Both functions write to the SQLite path given by `output=`. The optional
+`symbols` parameter filters `positions` / `orders` by symbol.
+`with_grafana_schema=False` (default) skips Grafana view/index setup; run
+`grafana-schema` once to set up the schema, then call `snapshot` repeatedly
+without this flag.
+
+Pass the `MT5Client` yielded by `mt5_session()` directly to
+`update_observability(client=...)`. This workflow calls the facade's canonical
+data methods (`account_info`, `positions`, `orders`, `terminal_info`); callers
+never need a pdmt5 client, and no raw pdmt5 method-name fallback logic is
+involved.
+
+```python
+from mt5cli import mt5_session, update_observability
+
+with mt5_session() as client:
+    update_observability(client=client, output="observability.db")
+```
+
+Schema and persistence (table DDL, Grafana views, and row inserts) belong to
+[Grafana](grafana.md); this module owns _when_ and _what_ to snapshot.