mt5cli 1.4.0__tar.gz → 1.4.1__tar.gz

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

@@ -0,0 +1,41 @@
+#!/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 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.1}/.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 ...`.
 

mt5cli-1.4.1/.github/CODEOWNERS

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

{mt5cli-1.4.0 → mt5cli-1.4.1}/.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.1}/.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.1}/.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.1/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.4.0
+Version: 1.4.1
 Summary: Generic MT5 data and execution infrastructure for Python applications
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -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
@@ -385,7 +385,6 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 
 ## Requirements
 
-- Python 3.11+
 - Windows OS (MetaTrader 5 requirement)
 - MetaTrader 5 platform installed
 

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

@@ -356,7 +356,6 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 
 ## Requirements
 
-- Python 3.11+
 - Windows OS (MetaTrader 5 requirement)
 - MetaTrader 5 platform installed
 

{mt5cli-1.4.0 → mt5cli-1.4.1}/docs/api/public-contract.md

@@ -24,10 +24,11 @@ in pdmt5 — the name changed, it was not simply moved.
 
 Downstream packages should import from the package root (`from mt5cli import
 ...`). The contract set `STABLE_SDK_EXPORTS` in `mt5cli.contract` enumerates
-every package-root symbol. Lower-level helpers (schema utilities, export
-functions, parser helpers, low-level MT5 wrappers) are available directly from
-their owning modules (`mt5cli.schemas`, `mt5cli.utils`, `mt5cli.converters`,
-`mt5cli.marketdata`, etc.) and are not part of the root SDK surface.
+every package-root symbol. Helpers promoted for downstream use, including selected configuration and
+parsing utilities, history timeframe resolution, and Grafana schema setup, are
+part of that root contract. Other low-level
+schema, export, conversion, and implementation helpers remain available only
+from their owning modules.
 
 ### Module responsibility map
 
@@ -56,13 +57,14 @@ These names are exported from `mt5cli` and enumerated in
 
 ### Session lifecycle and configuration
 
-| Symbol                                          | Role                                                                                                                                                                                                                                                                              |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MT5Client`                                     | The single connected client for data, history, calculations, order checking, and order sending                                                                                                                                                                                    |
-| `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields; `login` accepts `int \| str \| None` — numeric strings are coerced to `int`, blank strings are treated as unset, and `${ENV_VAR}` / `$ENV_NAME` placeholders in string parameters are expanded when `allow_whole_dollar_env=True` |
-| `mt5_session`                                   | Canonical context manager: initialize/login once, yield `MT5Client`, shut down once; a supplied `client=` remains caller-owned.                                                                                                                                                   |
-| `AccountSpec`                                   | Generic account group: symbols plus optional credentials                                                                                                                                                                                                                          |
-| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME`                                                                                                                                                                            |
+| Symbol                                          | Role                                                                                                                                                                                                                                                                                                 |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MT5Client`                                     | The single connected client for data, history, calculations, order checking, and order sending                                                                                                                                                                                                       |
+| `build_config`                                  | Build the underlying MT5 connection config from connection fields; `login` accepts `int \| str \| None` — numeric strings are coerced to `int`, blank strings are treated as unset, and `${ENV_VAR}` / `$ENV_NAME` placeholders in string parameters are expanded when `allow_whole_dollar_env=True` |
+| `substitute_mapping_values`                     | Generic selected-key environment substitution for downstream configuration adapters                                                                                                                                                                                                                  |
+| `mt5_session`                                   | Canonical context manager: initialize/login once, yield `MT5Client`, shut down once; a supplied `client=` remains caller-owned.                                                                                                                                                                      |
+| `AccountSpec`                                   | Generic account group: symbols plus optional credentials                                                                                                                                                                                                                                             |
+| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME`                                                                                                                                                                                               |
 
 ### Closed-bar rate helpers
 
@@ -93,6 +95,11 @@ timestamp normalization in downstream apps.
 See [History Collection (SQLite)](history.md) for schema, view naming, and ER
 diagrams.
 
+Shared package-root helpers used by downstream adapters include `Dataset`,
+`parse_timeframe`, and `resolve_history_timeframes`. These are stable exports;
+downstream applications should not import them from `mt5cli.utils` or
+`mt5cli.history`.
+
 ### Trading and sizing primitives (generic)
 
 These helpers implement broker-facing calculations only. They do not encode
@@ -108,7 +115,7 @@ strategy entries, exits, Kelly sizing, or signal logic.
 | `CalibrationStatus`, `ClockStatus`                                                                                             | Literal status types for clock calibration and normalization      |
 | `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                                   |
+| `calculate_margin_and_volume`, `calculate_volume_by_margin`, `calculate_account_projected_margin_ratio`                        | Margin budget and volume sizing                                   |
 | `normalize_order_volume`, `estimate_order_margin`, `calculate_positions_margin`                                                | Broker volume normalization and margin totals                     |
 | `calculate_positions_margin_by_symbol`                                                                                         | Per-symbol margin map (resilient, first-seen order)               |
 | `calculate_positions_margin_safe`                                                                                              | Summed total margin across symbols (failed symbols skipped)       |
@@ -230,8 +237,9 @@ workflows call the facade's canonical data methods (`account_info`, `positions`,
 | `grafana_realized_pnl` | Cumulative realized PnL per symbol    |
 | `grafana_trade_stats`  | Win/loss counts and profit per symbol |
 
-Lower-level helpers (`ensure_grafana_schema`, `create_grafana_views`,
-`create_grafana_indexes`, `create_snapshot_tables`, `start_snapshot_run`,
+`ensure_grafana_schema` is a stable package-root helper for downstream setup.
+Other lower-level helpers (`create_grafana_views`, `create_grafana_indexes`,
+`create_snapshot_tables`, `start_snapshot_run`,
 `insert_account_snapshot`, `insert_position_snapshots`, `insert_order_snapshots`,
 `insert_terminal_snapshot`, `record_snapshot_run`) are available directly from
 `mt5cli.grafana` and are not part of the package-root stable surface.
@@ -367,7 +375,7 @@ their own adapter layer.
 
 ## Contract verification
 
-`tests/test_contracts.py` asserts that every name in `STABLE_SDK_EXPORTS` is
+`tests/unit/test_contracts.py` asserts that every name in `STABLE_SDK_EXPORTS` is
 importable from `mt5cli`, that all package-root exports are covered by the
 stable set, and documents key closed-bar, SQLite loading, account-resolution,
 and trading-session behaviors.

{mt5cli-1.4.0 → mt5cli-1.4.1}/docs/index.md

@@ -224,7 +224,6 @@ See the [History schema diagram](api/history.md#entity-relationship-diagram) for
 
 ## Requirements
 
-- Python 3.11+
 - Windows OS (MetaTrader 5 requirement)
 - MetaTrader 5 platform
 

{mt5cli-1.4.0 → mt5cli-1.4.1}/mt5cli/__init__.py

@@ -9,7 +9,7 @@ strategy responsibilities.
 
 from importlib.metadata import version
 
-from .client import MT5Client, build_config, mt5_session
+from .client import MT5Client, build_config, mt5_session, substitute_mapping_values
 from .contract import STABLE_SDK_EXPORTS
 from .exceptions import (
     Mt5CliError,
@@ -17,6 +17,7 @@ from .exceptions import (
     Mt5OperationError,
     Mt5SchemaError,
 )
+from .grafana import ensure_grafana_schema
 from .history import (
     RateTarget,
     ThrottledHistoryUpdater,
@@ -26,6 +27,7 @@ from .history import (
     load_rate_series_by_granularity,
     load_rate_series_from_sqlite,
     report_rate_gaps,
+    resolve_history_timeframes,
     update_history,
     update_history_with_config,
 )
@@ -56,7 +58,6 @@ from .trading import (
     TickClockNormalizer,
     calculate_account_projected_margin_ratio,
     calculate_margin_and_volume,
-    calculate_new_position_margin_ratio,
     calculate_positions_margin,
     calculate_positions_margin_by_symbol,
     calculate_positions_margin_safe,
@@ -82,6 +83,7 @@ from .trading import (
     update_sltp_for_open_positions,
     update_trailing_stop_loss_for_open_positions,
 )
+from .utils import Dataset, parse_timeframe
 
 __version__ = version(__package__) if __package__ else None
 

{mt5cli-1.4.0 → mt5cli-1.4.1}/mt5cli/contract.py

@@ -123,11 +123,11 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "TickClockNormalizer",
     "RateTarget",
     "ThrottledHistoryUpdater",
+    "Dataset",
     "build_config",
     "build_rate_targets",
     "calculate_account_projected_margin_ratio",
     "calculate_margin_and_volume",
-    "calculate_new_position_margin_ratio",
     "calculate_projected_margin_ratio",
     "calculate_positions_margin",
     "calculate_positions_margin_by_symbol",
@@ -144,6 +144,7 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "detect_position_side",
     "determine_order_limits",
     "drop_forming_rate_bar",
+    "ensure_grafana_schema",
     "ensure_symbol_selected",
     "estimate_order_margin",
     "extract_tick_price",
@@ -157,11 +158,14 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "load_rate_series_from_sqlite",
     "mt5_session",
     "normalize_order_volume",
+    "parse_timeframe",
     "place_market_order",
     "report_rate_gaps",
     "resolve_broker_filling_mode",
     "resolve_account_spec",
     "resolve_account_specs",
+    "resolve_history_timeframes",
+    "substitute_mapping_values",
     "update_history",
     "update_history_with_config",
     "update_observability",

{mt5cli-1.4.0 → mt5cli-1.4.1}/mt5cli/trading.py

@@ -310,7 +310,6 @@ __all__ = [
     "TickClockNormalizer",
     "calculate_account_projected_margin_ratio",
     "calculate_margin_and_volume",
-    "calculate_new_position_margin_ratio",
     "calculate_positions_margin",
     "calculate_positions_margin_by_symbol",
     "calculate_positions_margin_safe",
@@ -2269,43 +2268,6 @@ def calculate_spread_ratio(client: _Mt5ClientProtocol, symbol: str) -> float:
     return (ask - bid) / ((ask + bid) / 2.0)
 
 
-def calculate_new_position_margin_ratio(
-    client: _Mt5ClientProtocol,
-    *,
-    symbol: str,
-    new_position_side: OrderSide | None = None,
-    new_position_volume: float = 0.0,
-) -> float:
-    """Return total margin/equity ratio after an optional hypothetical position.
-
-    Missing or falsy account ``equity``/``margin`` values are normalized to
-    ``0.0``, and the hypothetical order margin from ``order_calc_margin()`` is
-    accepted as-is without a positivity check.
-
-    Raises:
-        Mt5OperationError: If equity or required tick data is invalid.
-    """
-    account = get_account_snapshot(client)
-    equity = float(account.get("equity") or 0.0)
-    if equity <= 0:
-        msg = "Account equity must be positive to calculate margin ratio."
-        raise Mt5OperationError(msg)
-    margin = float(account.get("margin") or 0.0)
-    if new_position_side is not None and new_position_volume > 0:
-        side = _normalize_order_side(new_position_side)
-        price = extract_tick_price(
-            get_tick_snapshot(client, symbol), "ask" if side == "BUY" else "bid"
-        )
-        price = _require_tick_price(price, symbol)
-        order_type = (
-            client.mt5.ORDER_TYPE_BUY if side == "BUY" else client.mt5.ORDER_TYPE_SELL
-        )
-        margin += float(
-            client.order_calc_margin(order_type, symbol, new_position_volume, price),
-        )
-    return margin / equity
-
-
 def _account_equity(client: _Mt5ClientProtocol) -> float:
     account = get_account_snapshot(client)
     return _required_account_number(account, "equity", allow_zero=False)

{mt5cli-1.4.0 → mt5cli-1.4.1}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mt5cli"
-version = "1.4.0"
+version = "1.4.1"
 description = "Generic MT5 data and execution infrastructure for Python applications"
 authors = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 maintainers = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 license = "MIT"
 license-files = ["LICENSE"]
 readme = "README.md"
-requires-python = ">= 3.11, < 3.14"
+requires-python = ">= 3.11, < 3.15"
 dependencies = [
   "pdmt5 >= 1.2.0",
   "pandas >= 2.2.2",
@@ -175,7 +175,7 @@ addopts = [
   "--capture=no",
 ]
 pythonpath = ["."]
-testpaths = ["tests"]
+testpaths = ["tests/unit"]
 python_files = ["test_*.py", "*_test.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]

mt5cli-1.4.1/tests/cli/test_cli.bats

@@ -0,0 +1,122 @@
+#!/usr/bin/env bats
+
+# CLI integration tests for the installed mt5cli entry point.
+#
+# These cases only exercise paths that never connect to MetaTrader 5: help
+# output, SQLite-only commands, and validation failures. No case passes --yes,
+# so the suite can never place a live trade.
+
+setup_file() {
+  set -euo pipefail
+  uv sync
+}
+
+teardown_file() {
+  :
+}
+
+seed_rate_database() {
+  local database="$1"
+  cat > "${BATS_TEST_TMPDIR}/seed_rates.py" << 'PY'
+import sqlite3
+import sys
+
+with sqlite3.connect(sys.argv[1]) as conn:
+    conn.execute('CREATE TABLE "rate_EURUSD__M1_1"(time TEXT, close REAL)')
+    conn.executemany(
+        'INSERT INTO "rate_EURUSD__M1_1"(time, close) VALUES (?, ?)',
+        [("2024-01-01T00:00:00+00:00", 1.0), ("2024-01-01T00:02:00+00:00", 1.1)],
+    )
+PY
+  uv run python "${BATS_TEST_TMPDIR}/seed_rates.py" "${database}"
+}
+
+@test "pass with \"mt5cli --help\"" {
+  run uv run mt5cli --help
+  [[ "${status}" -eq 0 ]]
+}
+
+@test "pass with \"mt5cli collect-history --help\"" {
+  run uv run mt5cli --output "${BATS_TEST_TMPDIR}/history.db" collect-history --help
+  [[ "${status}" -eq 0 ]]
+}
+
+@test "pass with \"mt5cli order-send --help\"" {
+  run uv run mt5cli --output "${BATS_TEST_TMPDIR}/out.csv" order-send --help
+  [[ "${status}" -eq 0 ]]
+}
+
+@test "pass with \"mt5cli grafana-schema\"" {
+  run uv run mt5cli --output "${BATS_TEST_TMPDIR}/grafana.db" grafana-schema
+  [[ "${status}" -eq 0 ]]
+  [[ -f "${BATS_TEST_TMPDIR}/grafana.db" ]]
+}
+
+@test "pass with \"mt5cli grafana-schema\" run twice" {
+  run uv run mt5cli --output "${BATS_TEST_TMPDIR}/grafana.db" grafana-schema
+  [[ "${status}" -eq 0 ]]
+  run uv run mt5cli --output "${BATS_TEST_TMPDIR}/grafana.db" grafana-schema
+  [[ "${status}" -eq 0 ]]
+}
+
+@test "pass with \"mt5cli grafana-schema --publish-copy\"" {
+  run uv run mt5cli \
+    --output "${BATS_TEST_TMPDIR}/grafana.db" \
+    grafana-schema \
+    --publish-copy "${BATS_TEST_TMPDIR}/published.db"
+  [[ "${status}" -eq 0 ]]
+  [[ -f "${BATS_TEST_TMPDIR}/published.db" ]]
+}
+
+@test "pass with \"mt5cli history-gaps\"" {
+  seed_rate_database "${BATS_TEST_TMPDIR}/history.db"
+  run uv run mt5cli \
+    --output "${BATS_TEST_TMPDIR}/gaps.json" \
+    history-gaps \
+    --sqlite3 "${BATS_TEST_TMPDIR}/history.db"
+  [[ "${status}" -eq 0 ]]
+  [[ -f "${BATS_TEST_TMPDIR}/gaps.json" ]]
+}
+
+@test "fail with \"mt5cli history-gaps\" for a missing database" {
+  run uv run mt5cli \
+    --output "${BATS_TEST_TMPDIR}/gaps.json" \
+    history-gaps \
+    --sqlite3 "${BATS_TEST_TMPDIR}/no-such.db"
+  [[ "${status}" -ne 0 ]]
+  [[ ! -e "${BATS_TEST_TMPDIR}/no-such.db" ]]
+}
+
+@test "fail with \"mt5cli order-send\" without --yes" {
+  run uv run mt5cli \
+    --output "${BATS_TEST_TMPDIR}/out.csv" \
+    order-send \
+    --request '{"action": 1, "symbol": "EURUSD"}'
+  [[ "${status}" -ne 0 ]]
+  [[ ! -e "${BATS_TEST_TMPDIR}/out.csv" ]]
+}
+
+@test "fail with \"mt5cli close-positions\" without a symbol or ticket" {
+  run uv run mt5cli \
+    --output "${BATS_TEST_TMPDIR}/close.json" \
+    close-positions
+  [[ "${status}" -ne 0 ]]
+  [[ ! -e "${BATS_TEST_TMPDIR}/close.json" ]]
+}
+
+@test "fail with \"mt5cli collect-history\" without SQLite3 output" {
+  run uv run mt5cli \
+    --output "${BATS_TEST_TMPDIR}/history.csv" \
+    collect-history \
+    --symbol EURUSD \
+    --date-from 2024-01-01 \
+    --date-to 2024-02-01
+  [[ "${status}" -ne 0 ]]
+  [[ ! -e "${BATS_TEST_TMPDIR}/history.csv" ]]
+}
+
+@test "fail with an undetectable output format" {
+  run uv run mt5cli --output "${BATS_TEST_TMPDIR}/out.xyz" account-info
+  [[ "${status}" -ne 0 ]]
+  [[ ! -e "${BATS_TEST_TMPDIR}/out.xyz" ]]
+}

{mt5cli-1.4.0/tests → mt5cli-1.4.1/tests/unit}/test_contracts.py

@@ -526,7 +526,7 @@ class TestStableSdkContract:
     def test_documented_contract_identifies_runtime_export_set(self) -> None:
         """The public-contract document points to the same runtime authority."""
         contract_doc = (
-            Path(__file__).parents[1] / "docs" / "api" / "public-contract.md"
+            Path(__file__).parents[2] / "docs" / "api" / "public-contract.md"
         ).read_text(encoding="utf-8")
         assert "`mt5cli.STABLE_SDK_EXPORTS`" in contract_doc
         assert set(mt5cli.__all__) - {"STABLE_SDK_EXPORTS"} == set(STABLE_SDK_EXPORTS)
@@ -548,7 +548,7 @@ class TestStableSdkContract:
     ],
 )
 def test_pdmt5_pass_through_names_stay_out_of_public_contract(name: str) -> None:
-    """Downstream code must import pdmt5 types/constants directly from pdmt5.
+    """Low-level pdmt5 types/constants stay out of the stable package root.
 
     docs/api/public-contract.md documents that mt5cli is not a pass-through
     compatibility namespace for pdmt5; these names must never reappear on the

{mt5cli-1.4.0/tests → mt5cli-1.4.1/tests/unit}/test_examples.py

@@ -11,7 +11,7 @@ import pytest
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
-_EXAMPLES_DIR = Path(__file__).parent.parent / "examples" / "grafana"
+_EXAMPLES_DIR = Path(__file__).parents[2] / "examples" / "grafana"
 _DASHBOARDS_DIR = _EXAMPLES_DIR / "dashboards"