mt5cli 1.1.4__tar.gz → 1.1.5__tar.gz

{mt5cli-1.1.4 → mt5cli-1.1.5}/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Structure & Module Organization
 
-`mt5cli/` contains the package source. Important modules include `cli.py` for the Typer command-line app, `client.py` and `sdk.py` for public MT5 client/session APIs, `history.py` for SQLite history collection, `storage.py` and `converters.py` for export behavior, and `schemas.py` for normalized dataset contracts. `tests/` holds pytest coverage for CLI behavior, SDK contracts, trading helpers, history, and utilities. `docs/` and `mkdocs.yml` define the MkDocs site and API reference. `skills/mt5cli/SKILL.md` documents the mt5cli agent skill.
+`mt5cli/` contains the package source. Important modules include `cli.py` for the Typer command-line app, `client.py` and `sdk.py` for public MT5 client/session APIs, `history.py` for SQLite history collection, `trading.py` for trading helpers, `grafana.py` for Grafana schema support, `telemetry.py` for observability, `utils.py` and `converters.py` for export behavior, and `schemas.py` for normalized dataset contracts. `tests/` holds pytest coverage for CLI behavior, SDK contracts, trading helpers, history, and utilities. `docs/` and `mkdocs.yml` define the MkDocs site and API reference. `skills/mt5cli/SKILL.md` documents the mt5cli agent skill.
 
 ## Build, Test, and Development Commands
 

{mt5cli-1.1.4 → mt5cli-1.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.1.4
+Version: 1.1.5
 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>

{mt5cli-1.1.4 → mt5cli-1.1.5}/docs/api/history.md

@@ -20,6 +20,21 @@ append using dataset-specific keys (for example `ticket` on history tables, or
 Optional views are created when `--with-views` is set and the `history-deals` dataset
 was written.
 
+`ticks` and `symbols` are opt-in datasets (pass `--dataset ticks` /
+`--dataset symbols`); they are excluded from the default `rates`,
+`history-orders`, `history-deals` selection. Unlike the other datasets,
+`symbols` is not a time-windowed history table: each collection or update
+writes one row per requested symbol, timestamped with the collection's
+`date_to` (one-shot `collect-history`) or the update's end time (incremental
+`update_history`). It snapshots broker-reported symbol metadata (`point`,
+`digits`, `trade_contract_size`, `volume_min`, `volume_max`, `volume_step`,
+`trade_tick_size`, `trade_tick_value`, `currency_profit`) so downstream
+consumers can convert `rates.spread` (points) into a relative spread without a
+live terminal connection. Metadata is only valid for the account/broker that
+produced the snapshot. When a symbol's `point` is missing or zero, the row is
+still written with NULL metadata and a warning is logged — a bad symbol never
+aborts the rest of the sync.
+
 ### Entity-relationship diagram
 
 Sample layout for a full collection with `--with-views`:
@@ -79,6 +94,20 @@ erDiagram
         REAL fee
     }
 
+    symbols {
+        TEXT symbol "dedup key"
+        TEXT time "dedup key, snapshot moment"
+        REAL point
+        INTEGER digits
+        REAL trade_contract_size
+        REAL volume_min
+        REAL volume_max
+        REAL volume_step
+        REAL trade_tick_size
+        REAL trade_tick_value
+        TEXT currency_profit
+    }
+
     cash_events {
         INTEGER ticket
         TEXT symbol
@@ -106,6 +135,7 @@ erDiagram
     rates ||--o{ history_deals : "symbol (logical)"
     ticks ||--o{ history_deals : "symbol (logical)"
     history_orders ||--o{ history_deals : "order ~ ticket (logical)"
+    symbols ||--o{ rates : "symbol (logical)"
     history_deals ||--|| cash_events : "VIEW: type NOT IN (0,1)"
     history_deals ||--o{ positions_reconstructed : "VIEW: GROUP BY position_id"
 ```
@@ -118,6 +148,7 @@ erDiagram
 | `ticks`                   | table | `copy_ticks_range`   | Indexed on `(symbol, time)` when columns exist.                                             |
 | `history_orders`          | table | `history_orders_get` | Fetched per `--symbol`, then concatenated.                                                  |
 | `history_deals`           | table | `history_deals_get`  | Fetched per `--symbol`, then concatenated. Indexed on `(position_id, symbol)` when present. |
+| `symbols`                 | table | `symbol_info`        | Opt-in. One row per symbol per collection/update, snapshotted at `date_to` / update end.    |
 | `cash_events`             | view  | `history_deals`      | Non-trade deal types (deposits, balance ops, etc.). Requires `type` column.                 |
 | `positions_reconstructed` | view  | `history_deals`      | One row per closed `position_id`; volume-weighted prices and reversal stats.                |
 
@@ -240,7 +271,7 @@ frame = series["EURUSD", 1]  # keyed by (symbol, integer timeframe)
   `require_existing` is ignored.
 - `load_rate_series_from_sqlite()` returns a mapping keyed by
   `(symbol, integer timeframe)`. Unless `explicit_tables` is supplied, it
-  requires existing managed `rate_*` compatibility views and raises
+  requires existing managed `rate_*__*` compatibility views and raises
   `ValueError` when they are missing. Duplicate `(symbol, timeframe)` targets
   are rejected.
 - `load_rate_series_by_granularity()` is a thin wrapper that builds the targets,

{mt5cli-1.1.4 → mt5cli-1.1.5}/docs/api/public-contract.md

@@ -88,6 +88,7 @@ strategy entries, exits, Kelly sizing, or signal logic.
 | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
 | `get_account_snapshot`, `get_symbol_snapshot`, `get_tick_snapshot`, `get_positions_frame`                                      | Normalized account/symbol/tick/position views                     |
 | `extract_tick_price`                                                                                                           | Positive finite bid/ask extraction from tick mappings             |
+| `estimate_server_clock_offset_seconds`                                                                                         | Broker server clock offset from true UTC, via the latest tick     |
 | `detect_position_side`                                                                                                         | Net long / short / flat from open positions                       |
 | `calculate_spread_ratio`                                                                                                       | Relative bid-ask spread                                           |
 | `calculate_margin_and_volume`, `calculate_volume_by_margin`, `calculate_new_position_margin_ratio`                             | Margin budget and volume sizing                                   |

{mt5cli-1.1.4 → mt5cli-1.1.5}/docs/api/sdk.md

@@ -160,8 +160,8 @@ updater = ThrottledHistoryUpdater(
 )
 ```
 
-By default recoverable errors (`Mt5TradingError`, `Mt5RuntimeError`,
-`sqlite3.Error`, `ValueError`, `OSError`, and MT5 client capability
+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`

{mt5cli-1.1.4 → mt5cli-1.1.5}/docs/api/trading.md

@@ -236,6 +236,45 @@ or `None` result from the underlying client is normalized to an empty DataFrame.
 Downstream packages own all strategy-specific transformations. mt5cli does not
 provide entry-deal classification, Kelly sizing, or any betting-specific helpers.
 
+## Broker server clock offset
+
+MT5 tick, bar, and deal timestamps are epoch values labeled in the broker
+server's wall clock, which is commonly UTC+2 or UTC+3 rather than true UTC.
+Any code that mixes those timestamps with true UTC (freshness checks,
+trailing history windows) silently inherits the broker's offset as a bias
+unless it is measured and applied explicitly.
+
+`estimate_server_clock_offset_seconds()` reads the latest tick for a symbol
+and returns the broker's clock offset from true UTC, rounded to the nearest
+half hour, or `None` when no valid tick time is available. Pass the result to
+`fetch_recent_history_deals_for_trading_client()` via
+`server_clock_offset_seconds` to shift the trailing window so it covers the
+true most-recent deals:
+
+```python
+from mt5cli import (
+    create_trading_client,
+    estimate_server_clock_offset_seconds,
+    fetch_recent_history_deals_for_trading_client,
+)
+
+client = create_trading_client(login=12345, server="Broker-Demo")
+try:
+    offset = estimate_server_clock_offset_seconds(client, "JP225")
+    deals_df = fetch_recent_history_deals_for_trading_client(
+        client,
+        symbol="JP225",
+        hours=24,
+        server_clock_offset_seconds=offset,
+    )
+finally:
+    client.shutdown()
+```
+
+No offset is applied automatically anywhere; omitting
+`server_clock_offset_seconds` keeps the trailing window anchored to true UTC
+(current behavior, byte-identical to prior releases).
+
 ## Migration from application-local helpers
 
 | Application-local concern                                | mt5cli replacement                                                                      |
@@ -247,6 +286,7 @@ provide entry-deal classification, Kelly sizing, or any betting-specific helpers
 | Local order or position margin estimation                | `estimate_order_margin()`, `calculate_positions_margin()`                               |
 | Local closed-bar fetch from a trading session            | `fetch_latest_closed_rates_for_trading_client()`, `fetch_latest_closed_rates_indexed()` |
 | Local recent deal history fetch from a trading session   | `fetch_recent_history_deals_for_trading_client()`                                       |
+| Local broker server clock offset measurement             | `estimate_server_clock_offset_seconds()`                                                |
 | Local SL/TP price derivation                             | `determine_order_limits()`                                                              |
 | Throttled SQLite history loop with ad-hoc error handling | `ThrottledHistoryUpdater(suppress_errors=True)`                                         |
 

{mt5cli-1.1.4 → mt5cli-1.1.5}/docs/index.md

@@ -178,10 +178,10 @@ applications should prefer dedicated closing helpers or their own risk controls.
 
 ### Bulk Collection
 
-| Command           | Description                                                                                                                                                                      |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `collect-history` | Collect rates, history-orders, and history-deals (ticks opt-in via `--dataset ticks`) for one or more symbols into a single SQLite database (optional cash-event/position views) |
-| `history-gaps`    | Export a SQLite-only one-row-per-gap report from managed rate compatibility views without connecting to MT5                                                                      |
+| Command           | Description                                                                                                                                                                                                                |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `collect-history` | Collect rates, history-orders, and history-deals (ticks and symbol metadata opt-in via `--dataset ticks` / `--dataset symbols`) for one or more symbols into a single SQLite database (optional cash-event/position views) |
+| `history-gaps`    | Export a SQLite-only one-row-per-gap report from managed rate compatibility views without connecting to MT5                                                                                                                |
 
 ```bash
 mt5cli -o history.db collect-history \
@@ -193,16 +193,16 @@ mt5cli -o history.db collect-history \
 
 `collect-history` options:
 
-| Option         | Default                              | Description                                                                                                                |
-| -------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| `--symbol/-s`  | _required_                           | Symbol to collect (repeat for multiple).                                                                                   |
-| `--date-from`  | _required_                           | Start date in ISO 8601.                                                                                                    |
-| `--date-to`    | _required_                           | End date in ISO 8601.                                                                                                      |
-| `--dataset`    | rates, history-orders, history-deals | Repeatable: `rates`, `ticks`, `history-orders`, `history-deals`. Ticks are opt-in: pass `--dataset ticks` to include them. |
-| `--timeframe`  | `M1`                                 | Rates timeframe; recorded in a `timeframe` column on the `rates` table.                                                    |
-| `--flags`      | `ALL`                                | Tick copy flags forwarded to `copy_ticks_range`.                                                                           |
-| `--if-exists`  | `fail`                               | `append`, `replace`, or `fail` when a target table already exists.                                                         |
-| `--with-views` | off                                  | Add `cash_events` and `positions_reconstructed` views (requires the `history-deals` dataset).                              |
+| Option         | Default                              | Description                                                                                                                                                                     |
+| -------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--symbol/-s`  | _required_                           | Symbol to collect (repeat for multiple).                                                                                                                                        |
+| `--date-from`  | _required_                           | Start date in ISO 8601.                                                                                                                                                         |
+| `--date-to`    | _required_                           | End date in ISO 8601.                                                                                                                                                           |
+| `--dataset`    | rates, history-orders, history-deals | Repeatable: `rates`, `ticks`, `history-orders`, `history-deals`, `symbols`. Ticks and symbol metadata are opt-in: pass `--dataset ticks` / `--dataset symbols` to include them. |
+| `--timeframe`  | `M1`                                 | Rates timeframe; recorded in a `timeframe` column on the `rates` table.                                                                                                         |
+| `--flags`      | `ALL`                                | Tick copy flags forwarded to `copy_ticks_range`.                                                                                                                                |
+| `--if-exists`  | `fail`                               | `append`, `replace`, or `fail` when a target table already exists.                                                                                                              |
+| `--with-views` | off                                  | Add `cash_events` and `positions_reconstructed` views (requires the `history-deals` dataset).                                                                                   |
 
 History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `positions_reconstructed` view excludes positions with no closing deal, uses volume-weighted open/close prices, and reports reversal deals (`DEAL_ENTRY_INOUT`) via `volume_reversal` / `reversal_count`.
 

{mt5cli-1.1.4 → mt5cli-1.1.5}/mt5cli/__init__.py

@@ -66,6 +66,7 @@ from .trading import (
     determine_order_limits,
     ensure_symbol_selected,
     estimate_order_margin,
+    estimate_server_clock_offset_seconds,
     extract_tick_price,
     fetch_latest_closed_rates_for_trading_client,
     fetch_latest_closed_rates_indexed,
@@ -127,6 +128,7 @@ __all__ = [
     "drop_forming_rate_bar",
     "ensure_symbol_selected",
     "estimate_order_margin",
+    "estimate_server_clock_offset_seconds",
     "extract_tick_price",
     "fetch_latest_closed_rates",
     "fetch_latest_closed_rates_for_trading_client",

{mt5cli-1.1.4 → mt5cli-1.1.5}/mt5cli/cli.py

@@ -6,7 +6,7 @@ import json
 import logging
 import os
 import re
-import sqlite3
+from contextlib import closing
 from dataclasses import dataclass
 from datetime import datetime  # noqa: TC003
 from pathlib import Path  # noqa: TC003
@@ -17,7 +17,11 @@ import typer
 
 from . import sdk
 from .client import MT5Client
-from .history import report_rate_gaps, resolve_granularity_name
+from .history import (
+    open_existing_sqlite_database,
+    report_rate_gaps,
+    resolve_granularity_name,
+)
 from .trading import OrderExecutionResult, close_open_positions, create_trading_client
 from .utils import (
     DATETIME_TYPE,
@@ -33,6 +37,7 @@ from .utils import (
 )
 
 if TYPE_CHECKING:
+    import sqlite3
     from collections.abc import Callable
 
     from pdmt5 import Mt5Config
@@ -838,10 +843,15 @@ def history_gaps(
     """Export SQLite rate gaps without connecting to MT5.
 
     Raises:
-        typer.BadParameter: If no compatible rate view is available and no
-            explicit table is provided, or if granularity inference fails.
+        typer.BadParameter: If the source database does not exist, if no
+            compatible rate view is available and no explicit table is
+            provided, or if granularity inference fails.
     """
-    with sqlite3.connect(sqlite3_path) as conn:
+    try:
+        conn, _ = open_existing_sqlite_database(sqlite3_path)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc), param_hint="--sqlite3") from exc
+    with closing(conn):
         tables = list(table) if table else _default_gap_tables(conn)
         if not tables:
             msg = (
@@ -902,7 +912,8 @@ def collect_history(
             help=(
                 "Dataset to include (repeat for multiple)."
                 " Defaults to rates, history-orders, history-deals."
-                " Ticks are opt-in: pass --dataset ticks to include them."
+                " Ticks and symbols metadata are opt-in:"
+                " pass --dataset ticks or --dataset symbols to include them."
             ),
         ),
     ] = None,
@@ -943,6 +954,9 @@ def collect_history(
     Tables written depend on ``--dataset``: ``rates``, ``history_orders``,
     ``history_deals`` by default. ``ticks`` are opt-in: pass
     ``--dataset ticks`` to include them (tick data grows the database quickly).
+    ``symbols`` is also opt-in: pass ``--dataset symbols`` to snapshot
+    per-symbol metadata (point, digits, contract size, volume limits) at
+    ``date_to``, one row per symbol per collection.
     History datasets are fetched per symbol and concatenated. Rates rows carry
     the requested ``timeframe`` so appended runs at different timeframes remain
     distinguishable.

{mt5cli-1.1.4 → mt5cli-1.1.5}/mt5cli/contract.py

@@ -44,6 +44,7 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "drop_forming_rate_bar",
     "ensure_symbol_selected",
     "estimate_order_margin",
+    "estimate_server_clock_offset_seconds",
     "extract_tick_price",
     "fetch_latest_closed_rates",
     "fetch_latest_closed_rates_for_trading_client",

{mt5cli-1.1.4 → mt5cli-1.1.5}/mt5cli/history.py

@@ -5,15 +5,17 @@ from __future__ import annotations
 import logging
 import re
 import sqlite3
+from collections.abc import Mapping
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from typing import TYPE_CHECKING, Literal, SupportsInt, cast, overload
 
 import pandas as pd
+from pdmt5 import Mt5RuntimeError
 from pdmt5 import get_timeframe_name as _get_timeframe_name
 
-from .schemas import DEDUP_KEYS, DataKind, ensure_utc_columns
+from .schemas import DEDUP_KEYS, REQUIRED_COLUMNS, DataKind, ensure_utc_columns
 from .utils import (
     TIMEFRAME_NAMES,
     Dataset,
@@ -24,7 +26,7 @@ from .utils import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Mapping, Sequence
+    from collections.abc import Callable, Sequence
 
     from pdmt5 import Mt5DataClient
 
@@ -49,8 +51,18 @@ _HISTORY_DEDUP_KEYS: dict[Dataset, tuple[tuple[str, ...], ...]] = {
     Dataset.ticks: DEDUP_KEYS[DataKind.ticks],
     Dataset.history_orders: DEDUP_KEYS[DataKind.history_orders],
     Dataset.history_deals: DEDUP_KEYS[DataKind.history_deals],
+    Dataset.symbols: DEDUP_KEYS[DataKind.symbols],
 }
 
+_SYMBOLS_SNAPSHOT_FIELDS: tuple[str, ...] = tuple(
+    sorted(REQUIRED_COLUMNS[DataKind.symbols] - {"symbol", "time"}),
+)
+_SYMBOLS_FLOAT_FIELDS: tuple[str, ...] = tuple(
+    field
+    for field in _SYMBOLS_SNAPSHOT_FIELDS
+    if field not in {"currency_profit", "digits"}
+)
+
 _TRADE_DEAL_TYPES: tuple[int, int] = (0, 1)
 _TRADE_DEAL_TYPES_SQL = f"({', '.join(str(value) for value in _TRADE_DEAL_TYPES)})"
 
@@ -91,7 +103,8 @@ def resolve_history_datasets(datasets: set[Dataset] | None) -> set[Dataset]:
     Returns:
         ``DEFAULT_HISTORY_DATASETS`` (rates, history-orders, history-deals)
         when ``datasets`` is None, otherwise the configured selection (which
-        may be empty or explicitly include ``Dataset.ticks``).
+        may be empty or explicitly include ``Dataset.ticks`` /
+        ``Dataset.symbols``).
     """
     if datasets is None:
         return set(DEFAULT_HISTORY_DATASETS)
@@ -222,7 +235,7 @@ def _open_history_connection(
     return conn, True
 
 
-def _open_existing_sqlite_database(
+def open_existing_sqlite_database(
     conn_or_path: SqliteConnOrPath,
 ) -> tuple[sqlite3.Connection, bool]:
     """Open a read-only SQLite database or reuse an existing connection.
@@ -490,7 +503,7 @@ def load_rate_data(
         DataFrame indexed by ascending ``time``.
 
     """
-    conn, should_close = _open_existing_sqlite_database(conn_or_path)
+    conn, should_close = open_existing_sqlite_database(conn_or_path)
     try:
         return load_rate_data_from_connection(conn, table, count=count)
     finally:
@@ -899,8 +912,8 @@ def load_rate_series_from_sqlite(
             be unique. Omit when loading a single explicit ``table``.
         count: Optional number of most recent rows to load per series.
         explicit_tables: Optional explicit table or view names matching targets.
-            When omitted, managed ``rate_*`` compatibility views must already
-            exist in the database.
+            When omitted, managed ``rate_*__*`` compatibility views must
+            already exist in the database.
         table: Optional single table or view name to load directly.
 
     Returns:
@@ -943,7 +956,7 @@ def load_rate_series_from_sqlite(
         if explicit_tables is not None
         else None
     )
-    conn, should_close = _open_existing_sqlite_database(conn_or_path)
+    conn, should_close = open_existing_sqlite_database(conn_or_path)
     try:
         resolved_tables = tables or resolve_rate_tables(
             conn,
@@ -1639,9 +1652,9 @@ def create_positions_reconstructed_view(
 
 
 def drop_rate_compatibility_views(conn: sqlite3.Connection) -> None:
-    """Drop all mt5cli-managed ``rate_*`` compatibility views."""
+    """Drop all mt5cli-managed ``rate_*__*`` compatibility views."""
     rows = conn.execute(
-        "SELECT name FROM sqlite_master WHERE type = 'view' AND name GLOB 'rate_*'",
+        "SELECT name FROM sqlite_master WHERE type = 'view' AND name GLOB 'rate_*__*'",
     ).fetchall()
     for (view_name,) in rows:
         quoted_view_name = quote_sqlite_identifier(str(view_name))
@@ -1801,6 +1814,62 @@ def write_ticks_dataset(
     )
 
 
+def write_symbols_dataset(
+    conn: sqlite3.Connection,
+    client: Mt5DataClient,
+    symbols: Sequence[str],
+    snapshot_time: datetime,
+    if_exists: IfExists,
+    written_columns: dict[Dataset, set[str]],
+) -> bool:
+    """Snapshot per-symbol metadata (point, digits, contract size, volume limits).
+
+    Broker-reported symbol metadata is only valid for the account/broker that
+    produced the snapshot. When a symbol's metadata cannot be retrieved, or
+    when its ``point`` is missing or zero (the terminal has no valid metadata
+    for it), a row is still persisted with NULL metadata and a warning is
+    logged; the sync is never aborted for a single bad symbol.
+
+    Returns:
+        True if the symbols table was written.
+    """
+
+    def _fetch_symbol_frame(sym: str) -> pd.DataFrame:
+        try:
+            info = client.symbol_info_as_dict(symbol=sym)
+        except Mt5RuntimeError:
+            info = None
+        if not isinstance(info, Mapping):
+            logger.warning(
+                "Symbol %r metadata could not be retrieved; persisting NULL metadata.",
+                sym,
+            )
+            info = {}
+        if info.get("point"):
+            metadata = {field: info.get(field) for field in _SYMBOLS_SNAPSHOT_FIELDS}
+        else:
+            if info:
+                logger.warning(
+                    "Symbol %r has missing or zero point; persisting NULL metadata.",
+                    sym,
+                )
+            metadata = dict.fromkeys(_SYMBOLS_SNAPSHOT_FIELDS)
+        frame = pd.DataFrame([{"symbol": sym, "time": snapshot_time, **metadata}])
+        for field in _SYMBOLS_FLOAT_FIELDS:
+            frame[field] = frame[field].astype("float64")
+        frame["digits"] = frame["digits"].astype("Int64")
+        return frame
+
+    return _stream_symbol_frames(
+        conn,
+        symbols,
+        Dataset.symbols,
+        if_exists,
+        written_columns,
+        _fetch_symbol_frame,
+    )
+
+
 def write_history_dataset(
     conn: sqlite3.Connection,
     fetch: Callable[..., pd.DataFrame],
@@ -1935,6 +2004,25 @@ def _write_incremental_ticks(
             )
 
 
+def _write_incremental_symbols(
+    conn: sqlite3.Connection,
+    client: Mt5DataClient,
+    symbols: Sequence[str],
+    end_date: datetime,
+    written_columns: dict[Dataset, set[str]],
+    written_tables: set[Dataset],
+) -> None:
+    if write_symbols_dataset(
+        conn,
+        client,
+        symbols,
+        end_date,
+        IfExists.APPEND,
+        written_columns,
+    ):
+        written_tables.add(Dataset.symbols)
+
+
 def _write_incremental_history_orders(
     conn: sqlite3.Connection,
     client: Mt5DataClient,
@@ -2182,6 +2270,15 @@ def write_incremental_datasets(  # noqa: PLR0913
             dedup_scopes,
             include_account_events=include_account_events,
         )
+    if Dataset.symbols in selected_datasets:
+        _write_incremental_symbols(
+            conn,
+            client,
+            symbols,
+            end_date,
+            written_columns,
+            written_tables,
+        )
     _finalize_incremental_writes(
         conn,
         selected_datasets,
@@ -2259,4 +2356,13 @@ def write_collected_datasets(
         include_account_events=False,
     ):
         written_tables.add(Dataset.history_deals)
+    if Dataset.symbols in datasets and write_symbols_dataset(
+        conn,
+        client,
+        symbols,
+        date_to,
+        if_exists,
+        written_columns,
+    ):
+        written_tables.add(Dataset.symbols)
     return written_tables, written_columns

{mt5cli-1.1.4 → mt5cli-1.1.5}/mt5cli/schemas.py

@@ -46,6 +46,7 @@ class DataKind(StrEnum):
     positions = "positions"
     history_orders = "history_orders"
     history_deals = "history_deals"
+    symbols = "symbols"
 
 
 REQUIRED_COLUMNS: dict[DataKind, frozenset[str]] = {
@@ -108,6 +109,19 @@ REQUIRED_COLUMNS: dict[DataKind, frozenset[str]] = {
         "price",
         "profit",
     }),
+    DataKind.symbols: frozenset({
+        "symbol",
+        "time",
+        "point",
+        "digits",
+        "trade_contract_size",
+        "volume_min",
+        "volume_max",
+        "volume_step",
+        "trade_tick_size",
+        "trade_tick_value",
+        "currency_profit",
+    }),
 }
 
 _OPTIONAL_TIME_COLUMNS_BY_KIND: dict[DataKind, frozenset[str]] = {
@@ -135,6 +149,7 @@ DEDUP_KEYS: dict[DataKind, tuple[tuple[str, ...], ...]] = {
     DataKind.ticks: (("symbol", "time_msc"), ("symbol", "time")),
     DataKind.history_orders: (("ticket",), ("symbol", "time", "type")),
     DataKind.history_deals: (("ticket",), ("symbol", "time", "type", "entry")),
+    DataKind.symbols: (("symbol", "time"),),
 }
 
 

{mt5cli-1.1.4 → mt5cli-1.1.5}/mt5cli/sdk.py

@@ -369,16 +369,26 @@ def build_config(
 
 
 @contextmanager
-def connected_client(config: Mt5Config) -> Iterator[Mt5DataClient]:
+def connected_client(
+    config: Mt5Config,
+    *,
+    retry_count: int | None = None,
+) -> Iterator[Mt5DataClient]:
     """Initialize MT5, yield a connected client, and always shut down.
 
     Args:
         config: MT5 connection configuration.
+        retry_count: Number of MT5 initialization retries. Defaults to the
+            pdmt5 client default when omitted.
 
     Yields:
         Connected ``Mt5DataClient`` instance.
     """
-    client = Mt5DataClient(config=config)
+    client = (
+        Mt5DataClient(config=config)
+        if retry_count is None
+        else Mt5DataClient(config=config, retry_count=retry_count)
+    )
     try:
         client.initialize_and_login_mt5()
         yield client
@@ -389,17 +399,21 @@ def connected_client(config: Mt5Config) -> Iterator[Mt5DataClient]:
 def _run_with_client(
     config: Mt5Config,
     fetch_fn: Callable[[Mt5DataClient], T],
+    *,
+    retry_count: int | None = None,
 ) -> T:
     """Connect, run ``fetch_fn``, and shut down safely.
 
     Args:
         config: MT5 connection configuration.
         fetch_fn: Callable receiving a connected client.
+        retry_count: Number of MT5 initialization retries. Defaults to the
+            pdmt5 client default when omitted.
 
     Returns:
         Value returned by ``fetch_fn``.
     """
-    with connected_client(config) as client:
+    with connected_client(config, retry_count=retry_count) as client:
         return fetch_fn(client)
 
 
@@ -512,7 +526,7 @@ class Mt5CliClient:
     def _fetch_value(self, fetch_fn: Callable[[Mt5DataClient], T]) -> T:
         if self._client is not None:
             return fetch_fn(self._client)
-        return _run_with_client(self._config, fetch_fn)
+        return _run_with_client(self._config, fetch_fn, retry_count=self._retry_count)
 
     def _fetch(self, fetch_fn: Callable[[Mt5DataClient], pd.DataFrame]) -> pd.DataFrame:
         return self._fetch_value(fetch_fn)
@@ -992,7 +1006,9 @@ def update_history(  # noqa: PLR0913
         output: SQLite database path.
         symbols: Symbols to update.
         datasets: Datasets to include (defaults to rates, history-orders,
-            history-deals; pass ``{Dataset.ticks}`` to opt in to ticks).
+            history-deals; pass ``{Dataset.ticks}`` to opt in to ticks,
+            or ``{Dataset.symbols}`` to opt in to symbol metadata
+            snapshots).
         timeframes: Rate timeframes to update (defaults to all fixed MT5
             timeframes when None).
         flags: Tick copy flags as integer or name (e.g. ``ALL``).
@@ -1126,7 +1142,9 @@ class ThrottledHistoryUpdater:
         Args:
             output: SQLite database path.
             datasets: Datasets to include (defaults to rates, history-orders,
-                history-deals; pass ``{Dataset.ticks}`` to opt in to ticks).
+                history-deals; pass ``{Dataset.ticks}`` to opt in to ticks,
+                or ``{Dataset.symbols}`` to opt in to symbol metadata
+                snapshots).
             timeframes: Rate timeframes to update (defaults to all fixed MT5
                 timeframes).
             flags: Tick copy flags as integer or name (e.g. ``ALL``).
@@ -1259,7 +1277,9 @@ def collect_history(
         date_from: Start date.
         date_to: End date.
         datasets: Datasets to include (defaults to rates, history-orders,
-            history-deals; pass ``{Dataset.ticks}`` to opt in to ticks).
+            history-deals; pass ``{Dataset.ticks}`` to opt in to ticks,
+            or ``{Dataset.symbols}`` to opt in to symbol metadata
+            snapshots).
         timeframe: Rates timeframe as integer or name (e.g. ``M1``).
         flags: Tick copy flags as integer or name (e.g. ``ALL``).
         if_exists: Behavior when a target table already exists.