mt5cli 1.4.0__tar.gz → 1.4.2__tar.gz

mt5cli-1.4.2/.agents/skills/local-qa/scripts/qa.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+set -euox pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+COOLDOWN_DAYS=7
+export UV_EXCLUDE_NEWER="${COOLDOWN_DAYS} days"
+export NPM_CONFIG_MIN_RELEASE_AGE="${COOLDOWN_DAYS}"
+export PNPM_CONFIG_MINIMUM_RELEASE_AGE=$((COOLDOWN_DAYS * 24 * 60))
+
+# Python
+uv sync
+uv run ruff format .
+uv run ruff check --fix .
+uv run pyright .
+uv run pytest
+
+# Markdown and JSON
+npx -y prettier --write './**/*.{md,json}'
+
+# YAML
+git ls-files -z -- '*.yml' \
+  | xargs -0 -t uvx yamllint -d '{"extends": "relaxed", "rules": {"line-length": "disable"}}'
+
+# GitHub Actions
+case "${OSTYPE}" in
+  darwin* | linux*)
+    # Shell scripts
+    git ls-files -z -- '*.sh' '*.bash' '*.bats' \
+      | xargs -0 -t shfmt --write --indent=2 --binary-next-line --case-indent --space-redirects
+    git ls-files -z -- '*.sh' '*.bash' '*.bats' \
+      | xargs -0 -t shellcheck
+
+    # GitHub Actions
+    zizmor --fix=safe .github/workflows
+    git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t actionlint
+    checkov --framework=all --output=github_failed_only --directory=.
+    ;;
+  *)
+    echo 'GitHub Actions and shell script linting is only supported on Linux and macOS.'
+    ;;
+esac

{mt5cli-1.4.0 → mt5cli-1.4.2}/.agents/skills/mt5cli/SKILL.md

@@ -12,8 +12,8 @@ command. Output format is auto-detected from the file extension (`.csv`,
 
 ## Requirements
 
-- Python 3.11+ on Windows with MetaTrader 5 installed (pdmt5 requires the
-  MT5 terminal).
+MT5 terminal).
+
 - Install: `pip install -U mt5cli MetaTrader5`.
 - In this repo, run via `uv run mt5cli ...` or `uv run python -m mt5cli ...`.
 
@@ -41,8 +41,10 @@ Global options MUST precede the subcommand.
 
 ### Parameter value formats
 
-- **Datetimes** (`--date-from`, `--date-to`): ISO 8601 (`2024-01-01` or
-  `2024-01-01T12:00:00+00:00`). Naive values are treated as UTC.
+- **Datetimes** (`--date-from`, `--date-to`): offset-free ISO 8601 values
+  (`2024-01-01` or `2024-01-01T12:00:00`). MT5 bounds are timezone-naive
+  trade-server wall-clock values; offset-bearing values are rejected and no
+  UTC-to-server-time conversion is inferred.
 - **Timeframe** (`--timeframe`): `M1`, `M2`, `M3`, `M4`, `M5`, `M6`, `M10`,
   `M12`, `M15`, `M20`, `M30`, `H1`, `H2`, `H3`, `H4`, `H6`, `H8`, `H12`,
   `D1`, `W1`, `MN1`, or the raw integer.

mt5cli-1.4.2/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner
+* @dceoy

{mt5cli-1.4.0 → mt5cli-1.4.2}/.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
       || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
     permissions:
       contents: read
-    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-lint-and-scan.yml@main   # zizmor: ignore[unpinned-uses]
+    uses: dceoy/gha-for-devops/.github/workflows/python-package-lint-and-scan.yml@main   # zizmor: ignore[unpinned-uses]
     with:
       package-path: .
       runs-on: windows-latest
@@ -46,32 +46,28 @@ jobs:
       || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
     permissions:
       contents: read
-    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-test.yml@main  # zizmor: ignore[unpinned-uses]
+    uses: dceoy/gha-for-devops/.github/workflows/python-package-test.yml@main  # zizmor: ignore[unpinned-uses]
     with:
       package-path: .
       runs-on: windows-latest
-  minimum-dependency-smoke-test:
+  bats-test:
     if: >
       github.event_name == 'push'
       || github.event_name == 'pull_request'
       || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
     permissions:
       contents: read
-    runs-on: windows-latest
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
-      - name: Check CLI help with minimum Click and Typer versions
-        run: uv run --with click==8.4.0 --with typer==0.26.0 mt5cli --help
+    uses: dceoy/gha-for-devops/.github/workflows/bats-test.yml@main  # zizmor: ignore[unpinned-uses]
+    with:
+      search-path: ./tests/cli/
+      runs-on: windows-latest
   python-docs-deploy:
     if: >
       github.event_name == 'push'
       || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'docs-deploy')
     permissions:
       contents: write
-    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-mkdocs-gh-deploy.yml@main  # zizmor: ignore[unpinned-uses]
+    uses: dceoy/gha-for-devops/.github/workflows/python-package-mkdocs-gh-deploy.yml@main  # zizmor: ignore[unpinned-uses]
     with:
       package-path: .
       runs-on: ubuntu-slim
@@ -86,7 +82,7 @@ jobs:
       contents: read
       security-events: write
       actions: read
-    uses: dceoy/gh-actions-for-devops/.github/workflows/github-codeql-analysis.yml@main  # zizmor: ignore[unpinned-uses]
+    uses: dceoy/gha-for-devops/.github/workflows/github-codeql-analysis.yml@main  # zizmor: ignore[unpinned-uses]
     with:
       language: >
         ["python"]
@@ -96,7 +92,8 @@ jobs:
     needs:
       - python-lint-and-scan
       - python-test
-    uses: dceoy/gh-actions-for-devops/.github/workflows/dependabot-auto-merge.yml@main  # zizmor: ignore[unpinned-uses]
+      - bats-test
+    uses: dceoy/gha-for-devops/.github/workflows/dependabot-auto-merge.yml@main  # zizmor: ignore[unpinned-uses]
     permissions:
       contents: write
       pull-requests: write

{mt5cli-1.4.0 → mt5cli-1.4.2}/.github/workflows/claude.yml

@@ -35,7 +35,7 @@ jobs:
       issues: write
       id-token: write
       actions: read
-    uses: dceoy/gh-actions-for-devops/.github/workflows/claude-code-review.yml@main  # zizmor: ignore[unpinned-uses]
+    uses: dceoy/gha-for-devops/.github/workflows/claude-code-review.yml@main  # zizmor: ignore[unpinned-uses]
     secrets:
       CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}  # zizmor: ignore[secrets-outside-env]
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -51,7 +51,7 @@ jobs:
       issues: write
       id-token: write
       actions: read
-    uses: dceoy/gh-actions-for-devops/.github/workflows/claude-code-bot.yml@main  # zizmor: ignore[unpinned-uses]
+    uses: dceoy/gha-for-devops/.github/workflows/claude-code-bot.yml@main  # zizmor: ignore[unpinned-uses]
     secrets:
       CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}  # zizmor: ignore[secrets-outside-env]
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{mt5cli-1.4.0 → mt5cli-1.4.2}/.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
     permissions:
       contents: write
       id-token: write
-    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-release-on-pypi-and-github.yml@main  # zizmor: ignore[unpinned-uses]
+    uses: dceoy/gha-for-devops/.github/workflows/python-package-release-on-pypi-and-github.yml@main  # zizmor: ignore[unpinned-uses]
     with:
       package-path: .
       create-github-release: true
@@ -39,6 +39,6 @@ jobs:
           name: ${{ needs.build-and-release.outputs.distribution-artifact-name }}
           path: dist/
       - name: Publish distribution 📦 to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
         with:
           verbose: true

mt5cli-1.4.2/AGENTS.md

@@ -0,0 +1,29 @@
+# Repository Guidelines
+
+## Build, Test, and Development Commands
+
+Use `.agents/skills/local-qa/SKILL.md` for pre-handoff QA. It runs `.agents/skills/local-qa/scripts/qa.sh`, which formats, lints, type-checks, tests, formats Markdown, and checks GitHub workflows.
+
+`bats --verbose-run ./tests/cli/` runs the Windows/MT5-oriented CLI tests against the installed `mt5cli` entry point. These require a Windows environment where `uv sync` can install MetaTrader5; state clearly when they were not run.
+
+`skills/mt5cli/SKILL.md` documents the mt5cli agent skill.
+
+## Coding Style & Naming Conventions
+
+Preserve the package’s small, typed helper style rather than adding broad abstractions.
+
+## Design Principles
+
+Apply KISS, DRY, and YAGNI when changing code. Prefer the simplest implementation that satisfies the current CLI/API contract. Remove duplication when shared behavior is already proven by at least two concrete call sites, but avoid generic helpers for speculative reuse. Do not add configuration flags, extension hooks, or alternate backends until a real repository use case requires them.
+
+## Testing Guidelines
+
+Parametrize unit tests with `pytest.mark.parametrize` when the same behavior needs coverage across multiple inputs. Mock MT5/pdmt5 boundaries; do not require a live MetaTrader terminal in unit tests.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses concise imperative commits, sometimes with conventional prefixes such as `feat:` or `chore:` and PR numbers appended by GitHub. Keep commits scoped to one logical change. Pull requests should describe behavior changes, note tests run, link related issues, and call out MT5/live-trading risk where relevant.
+
+## Security & Configuration Tips
+
+Never commit account credentials, broker passwords, exported private data, or local `.venv` contents. Treat `order_send` and CLI `order-send --yes` as live execution paths; gate examples and tests so they cannot place real trades accidentally.

{mt5cli-1.4.0 → mt5cli-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.4.0
+Version: 1.4.2
 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>
@@ -15,7 +15,7 @@ Classifier: Operating System :: Microsoft :: Windows
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Office/Business :: Financial :: Investment
-Requires-Python: <3.14,>=3.11
+Requires-Python: <3.15,>=3.11
 Requires-Dist: pandas>=2.2.2
 Requires-Dist: pdmt5>=1.2.0
 Requires-Dist: typer>=0.26.0
@@ -50,7 +50,7 @@ Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data han
 - **Comprehensive data access**: Rates, ticks, account info, symbols, orders, positions, and trading history
 - **Flexible timeframes**: Named timeframes (M1, H1, D1, etc.) and numeric values
 - **Connection management**: Optional credentials, server, and timeout configuration
-- **SQLite rate loading**: Load mt5cli-managed rate tables/views for offline workflows
+- **SQLite rate loading**: Load canonical normalized `rates` storage for offline workflows
 
 ## Installation
 
@@ -69,7 +69,7 @@ pip install -U "mt5cli[parquet]" MetaTrader5
 Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
 
 ```python
-from datetime import UTC, datetime
+from datetime import datetime
 from pathlib import Path
 
 from mt5cli import (
@@ -103,8 +103,8 @@ export_dataframe(closed_rates, Path("rates.csv"), "csv")
 collect_history(
     Path("history.db"),
     symbols=["EURUSD"],
-    date_from=datetime(2024, 1, 1, tzinfo=UTC),
-    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+    date_from=datetime(2024, 1, 1),
+    date_to=datetime(2024, 2, 1),
     datasets={Dataset.rates, Dataset.history_deals},
 )
 
@@ -113,9 +113,16 @@ update_history_with_config(
     output="history.db",
     symbols=["EURUSD"],
     config=build_config(login=12345),
+    date_to=datetime(2024, 2, 1),
 )
 ```
 
+MT5 query bounds are timezone-naive trade-server wall-clock datetimes, as
+required by pdmt5. Incremental history updates require an explicit `date_to`
+because mt5cli cannot determine the current trade-server time. Offset-bearing
+strings and timezone-aware `datetime` objects are rejected; mt5cli does not
+infer or strip offsets to perform a conversion.
+
 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.
@@ -335,6 +342,8 @@ 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 datetime import datetime
+
 from pdmt5 import Mt5Config
 from mt5cli import update_history_with_config
 from mt5cli.utils import Dataset
@@ -347,19 +356,17 @@ update_history_with_config(
     datasets={Dataset.rates, Dataset.history_deals},
     timeframes=["M1", "H1"],  # default: all fixed MT5 timeframes
     lookback_hours=24,
-    create_rate_views=True,
+    date_to=datetime(2024, 2, 1),
     with_views=True,
     include_account_events=True,
 )
 ```
 
 - **`collect-history`**: explicit date-range export into SQLite.
-- **`update_history`**: incremental append based on existing SQLite `MAX(time)` per symbol (and timeframe for rates); account-level deals use a separate cursor when `include_account_events=True`.
+- **`update_history`**: incremental append based on existing SQLite `MAX(time)` per symbol (and timeframe for rates); account-level deals use a separate cursor when `include_account_events=True`. Pass an explicit naive trade-server `date_to`; mt5cli cannot determine the current server time. Rates are persisted only in the canonical normalized `rates` table.
 - **`rates` table**: normalized storage with `symbol` and `timeframe` columns.
-- **Rate compatibility views**: mt5cli manages all `rate_*` views. Naming is `rate_<symbol>__<timeframe>` when a symbol has one timeframe, otherwise `rate_<symbol>__<granularity>_<timeframe>` (for example `rate_EURUSD__M1_1`). Stale `rate_*` views are dropped and recreated when rates change for offline downstream tools.
-- **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.
+- **Explicit table loading**: use `load_rate_data()` / `load_rate_data_from_connection()` for intentionally named custom SQLite rate tables.
+- **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs and `load_rate_series_from_sqlite()` to load canonical `rates` rows into a mapping keyed by `(symbol, integer timeframe)`. Pass `explicit_tables` only for intentionally named custom tables; duplicate `(symbol, timeframe)` targets are rejected.
 - **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")`.
 
@@ -376,7 +383,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`, 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`.
+- **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, date_to=...)` 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.
@@ -385,7 +392,6 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 
 ## Requirements
 
-- Python 3.11+
 - Windows OS (MetaTrader 5 requirement)
 - MetaTrader 5 platform installed
 
@@ -435,7 +441,7 @@ updater = ThrottledHistoryUpdater(
     output="history.db", interval_seconds=60, suppress_errors=True
 )
 with mt5_session(Mt5Config(login=login)) as client:
-    updater.update(client, ["EURUSD"])
+    updater.update(client, ["EURUSD"], date_to="2024-02-01")
 ```
 
 Read-only collectors can keep using `mt5_session()` and `MT5Client`.

{mt5cli-1.4.0 → mt5cli-1.4.2}/README.md

@@ -21,7 +21,7 @@ Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data han
 - **Comprehensive data access**: Rates, ticks, account info, symbols, orders, positions, and trading history
 - **Flexible timeframes**: Named timeframes (M1, H1, D1, etc.) and numeric values
 - **Connection management**: Optional credentials, server, and timeout configuration
-- **SQLite rate loading**: Load mt5cli-managed rate tables/views for offline workflows
+- **SQLite rate loading**: Load canonical normalized `rates` storage for offline workflows
 
 ## Installation
 
@@ -40,7 +40,7 @@ pip install -U "mt5cli[parquet]" MetaTrader5
 Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
 
 ```python
-from datetime import UTC, datetime
+from datetime import datetime
 from pathlib import Path
 
 from mt5cli import (
@@ -74,8 +74,8 @@ export_dataframe(closed_rates, Path("rates.csv"), "csv")
 collect_history(
     Path("history.db"),
     symbols=["EURUSD"],
-    date_from=datetime(2024, 1, 1, tzinfo=UTC),
-    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+    date_from=datetime(2024, 1, 1),
+    date_to=datetime(2024, 2, 1),
     datasets={Dataset.rates, Dataset.history_deals},
 )
 
@@ -84,9 +84,16 @@ update_history_with_config(
     output="history.db",
     symbols=["EURUSD"],
     config=build_config(login=12345),
+    date_to=datetime(2024, 2, 1),
 )
 ```
 
+MT5 query bounds are timezone-naive trade-server wall-clock datetimes, as
+required by pdmt5. Incremental history updates require an explicit `date_to`
+because mt5cli cannot determine the current trade-server time. Offset-bearing
+strings and timezone-aware `datetime` objects are rejected; mt5cli does not
+infer or strip offsets to perform a conversion.
+
 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.
@@ -306,6 +313,8 @@ 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 datetime import datetime
+
 from pdmt5 import Mt5Config
 from mt5cli import update_history_with_config
 from mt5cli.utils import Dataset
@@ -318,19 +327,17 @@ update_history_with_config(
     datasets={Dataset.rates, Dataset.history_deals},
     timeframes=["M1", "H1"],  # default: all fixed MT5 timeframes
     lookback_hours=24,
-    create_rate_views=True,
+    date_to=datetime(2024, 2, 1),
     with_views=True,
     include_account_events=True,
 )
 ```
 
 - **`collect-history`**: explicit date-range export into SQLite.
-- **`update_history`**: incremental append based on existing SQLite `MAX(time)` per symbol (and timeframe for rates); account-level deals use a separate cursor when `include_account_events=True`.
+- **`update_history`**: incremental append based on existing SQLite `MAX(time)` per symbol (and timeframe for rates); account-level deals use a separate cursor when `include_account_events=True`. Pass an explicit naive trade-server `date_to`; mt5cli cannot determine the current server time. Rates are persisted only in the canonical normalized `rates` table.
 - **`rates` table**: normalized storage with `symbol` and `timeframe` columns.
-- **Rate compatibility views**: mt5cli manages all `rate_*` views. Naming is `rate_<symbol>__<timeframe>` when a symbol has one timeframe, otherwise `rate_<symbol>__<granularity>_<timeframe>` (for example `rate_EURUSD__M1_1`). Stale `rate_*` views are dropped and recreated when rates change for offline downstream tools.
-- **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.
+- **Explicit table loading**: use `load_rate_data()` / `load_rate_data_from_connection()` for intentionally named custom SQLite rate tables.
+- **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs and `load_rate_series_from_sqlite()` to load canonical `rates` rows into a mapping keyed by `(symbol, integer timeframe)`. Pass `explicit_tables` only for intentionally named custom tables; duplicate `(symbol, timeframe)` targets are rejected.
 - **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")`.
 
@@ -347,7 +354,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`, 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`.
+- **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, date_to=...)` 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.
@@ -356,7 +363,6 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 
 ## Requirements
 
-- Python 3.11+
 - Windows OS (MetaTrader 5 requirement)
 - MetaTrader 5 platform installed
 
@@ -406,7 +412,7 @@ updater = ThrottledHistoryUpdater(
     output="history.db", interval_seconds=60, suppress_errors=True
 )
 with mt5_session(Mt5Config(login=login)) as client:
-    updater.update(client, ["EURUSD"])
+    updater.update(client, ["EURUSD"], date_to="2024-02-01")
 ```
 
 Read-only collectors can keep using `mt5_session()` and `MT5Client`.