mt5cli 1.4.2__tar.gz → 1.5.0__tar.gz

{mt5cli-1.4.2 → mt5cli-1.5.0}/.agents/skills/local-qa/scripts/qa.sh

@@ -32,9 +32,9 @@ case "${OSTYPE}" in
       | xargs -0 -t shellcheck
 
     # GitHub Actions
-    zizmor --fix=safe .github/workflows
+    uvx zizmor --fix=safe .github/workflows
     git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t actionlint
-    checkov --framework=all --output=github_failed_only --directory=.
+    uvx checkov --framework=all --output=github_failed_only --directory=.
     ;;
   *)
     echo 'GitHub Actions and shell script linting is only supported on Linux and macOS.'

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

@@ -27,8 +27,7 @@ jobs:
     if: >
       github.event_name == 'pull_request'
       && (! github.event.pull_request.draft)
-      && (! startsWith(github.head_ref, 'dependabot/'))
-      && (! startsWith(github.head_ref, 'renovate/'))
+      && github.event.pull_request.user.type != 'Bot'
     permissions:
       contents: read
       pull-requests: write
@@ -46,7 +45,7 @@ jobs:
       || (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude'))
       || (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
     permissions:
-      contents: read
+      contents: write
       pull-requests: write
       issues: write
       id-token: write

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mt5cli
-Version: 1.4.2
+Version: 1.5.0
 Summary: Generic MT5 data and execution infrastructure for Python applications
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>

{mt5cli-1.4.2 → mt5cli-1.5.0}/docs/api/public-contract.md

@@ -39,6 +39,7 @@ operational capability still has exactly one owning module:
 | Module                 | Owns                                                                                                                                        |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | `mt5cli.client`        | Connection lifecycle (`build_config`, `mt5_session`, `MT5Client`); the sole session factory                                                 |
+| `mt5cli.lifecycle`     | Account selection within an already-active persistent MT5 session (`switch_account`)                                                        |
 | `mt5cli.marketdata`    | Stateless one-off market-data reads and multi-account rate collection (`AccountSpec`, `collect_latest_rates_for_accounts`, etc.)            |
 | `mt5cli.history`       | Legacy history collection, incremental updates, and SQLite storage (`collect_history`, `update_history`, `write_*_dataset`)                 |
 | `mt5cli.rates`         | Canonical rate persistence/loading and stable update wrappers (`load_rate_series_from_sqlite`, `update_history`, `ThrottledHistoryUpdater`) |
@@ -66,6 +67,7 @@ These names are exported from `mt5cli` and enumerated in
 | `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.                                                                                                                                                                      |
+| `switch_account`                                | Change the account selected by an already-active persistent `MT5Client` with MT5 `login()` only; verifies the requested login/server and does not reinitialize or shut down the terminal                                                                                                             |
 | `Mt5Config`                                     | Canonical pdmt5 connection configuration type returned by `build_config` and accepted by managed-session wrappers                                                                                                                                                                                    |
 | `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`                                                                                                                                                                                               |
@@ -374,4 +376,4 @@ their own adapter layer.
 `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.
+and trading-session behaviors.

mt5cli-1.5.0/mt5cli/lifecycle.py

@@ -0,0 +1,87 @@
+"""Persistent MT5 session lifecycle helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from pdmt5 import Mt5RuntimeError
+
+from .exceptions import Mt5ConnectionError, normalize_mt5_exception
+
+if TYPE_CHECKING:
+    from pdmt5 import Mt5DataClient
+
+    from .client import MT5Client
+
+
+def _account_matches(account: Any, *, login: int, server: str | None) -> bool:  # noqa: ANN401
+    """Return whether an MT5 account snapshot matches the requested account."""
+    if getattr(account, "login", None) != login:
+        return False
+    return server is None or getattr(account, "server", None) == server
+
+
+def switch_account(
+    client: MT5Client,
+    *,
+    login: int,
+    password: str | None = None,
+    server: str | None = None,
+    timeout: int | None = None,
+) -> None:
+    """Switch an active persistent MT5 session without reinitializing the terminal.
+
+    The configured account on ``client`` is intentionally left unchanged, but this
+    does not restore the prior account. For a self-owned client
+    (``with MT5Client(...) as client:``), exiting and re-entering reconnects using
+    the original configuration. For clients obtained via ``mt5_session()`` or
+    ``from_connected_client()`` (the common case), exiting and re-entering ``client``
+    has no effect on the connection at all, so the switched account persists for the
+    life of the terminal session.
+
+    Args:
+        client: An already-entered ``MT5Client`` with a persistent connection and
+            an already-active account.
+        login: Target MT5 account login.
+        password: Optional target account password.
+        server: Optional target trade server.
+        timeout: Optional MT5 login timeout in milliseconds.
+
+    Raises:
+        Mt5ConnectionError: If the client is not active, has no active account,
+            or the account switch fails.
+    """
+    connected = cast("Mt5DataClient | None", getattr(client, "_client", None))
+    if connected is None or not getattr(connected, "_is_initialized", True):
+        # pdmt5 auto-initializes on the first call, so an externally-bound
+        # inactive client must be rejected here.
+        msg = "MT5 account switching requires an active persistent session."
+        raise Mt5ConnectionError(msg)
+
+    try:
+        account = connected.account_info()
+        if _account_matches(account, login=login, server=server):
+            return
+        login_succeeded = connected.login(
+            login=login,
+            password=password,
+            server=server,
+            timeout=timeout,
+        )
+        last_error = None if login_succeeded else connected.last_error()
+        active_account = connected.account_info() if login_succeeded else None
+    except Mt5RuntimeError as exc:
+        normalized = normalize_mt5_exception(exc)
+        raise normalized from exc
+
+    if not login_succeeded:
+        msg = f"MT5 account switch failed: {last_error}"
+        raise Mt5ConnectionError(msg)
+    if not _account_matches(active_account, login=login, server=server):
+        msg = (
+            "MT5 account switch did not activate the requested account: "
+            f"requested login={login}, server={server!r}, "
+            f"active login={getattr(active_account, 'login', None)!r}, "
+            f"server={getattr(active_account, 'server', None)!r}"
+        )
+        raise Mt5ConnectionError(msg)

{mt5cli-1.4.2 → mt5cli-1.5.0}/mt5cli/sdk.py

@@ -20,6 +20,7 @@ from .history import (
     report_rate_gaps,
     resolve_history_timeframes,
 )
+from .lifecycle import switch_account
 from .marketdata import (
     AccountSpec,
     collect_latest_closed_rates_by_granularity,

{mt5cli-1.4.2 → mt5cli-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mt5cli"
-version = "1.4.2"
+version = "1.5.0"
 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"}]

mt5cli-1.5.0/tests/unit/test_lifecycle.py

@@ -0,0 +1,145 @@
+"""Tests for persistent MT5 session lifecycle helpers."""
+
+from __future__ import annotations
+
+from types import ModuleType, SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+from pdmt5 import Mt5DataClient, Mt5RuntimeError
+
+from mt5cli import MT5Client, Mt5ConnectionError, switch_account
+
+
+def _connected_client(raw_client: MagicMock) -> MT5Client:
+    """Return an MT5Client facade bound to a caller-owned active client."""
+    return MT5Client.from_connected_client(raw_client)
+
+
+@pytest.mark.parametrize(
+    ("active_login", "active_server", "requested_server", "expect_login"),
+    [
+        pytest.param(222, "Demo", "Demo", False, id="same-login-same-server"),
+        pytest.param(222, "Demo", None, False, id="same-login-no-server-constraint"),
+        pytest.param(111, "Demo", "Demo", True, id="different-login"),
+        pytest.param(222, "Other", "Demo", True, id="same-login-different-server"),
+    ],
+)
+def test_switch_account_pre_switch_match_decision(
+    active_login: int,
+    active_server: str | None,
+    requested_server: str | None,
+    expect_login: bool,
+) -> None:
+    """The pre-switch account-match check decides whether login() runs."""
+    raw_client = MagicMock()
+    active_account = SimpleNamespace(login=active_login, server=active_server)
+    raw_client.account_info.side_effect = [
+        active_account,
+        SimpleNamespace(login=222, server=requested_server or active_server),
+    ]
+    raw_client.login.return_value = True
+    client = _connected_client(raw_client)
+
+    switch_account(client, login=222, server=requested_server)
+
+    assert raw_client.login.called is expect_login
+    raw_client.shutdown.assert_not_called()
+
+
+def test_switch_account_uses_login_without_reinitializing_terminal() -> None:
+    """Changing accounts calls login only and verifies the resulting account."""
+    raw_client = MagicMock()
+    raw_client.account_info.side_effect = [
+        SimpleNamespace(login=111, server="Demo"),
+        SimpleNamespace(login=222, server="Demo"),
+    ]
+    raw_client.login.return_value = True
+    client = _connected_client(raw_client)
+
+    switch_account(
+        client,
+        login=222,
+        password="secret",
+        server="Demo",
+        timeout=60_000,
+    )
+
+    raw_client.login.assert_called_once_with(
+        login=222,
+        password="secret",
+        server="Demo",
+        timeout=60_000,
+    )
+    raw_client.initialize_and_login_mt5.assert_not_called()
+    raw_client.shutdown.assert_not_called()
+
+
+def test_switch_account_requires_active_persistent_session() -> None:
+    """Transient clients cannot switch an account without opening a session."""
+    client = MT5Client()
+
+    with pytest.raises(Mt5ConnectionError, match="active persistent session"):
+        switch_account(client, login=222)
+
+
+def test_switch_account_rejects_inactive_externally_bound_client() -> None:
+    """An uninitialized real client cannot trigger pdmt5's auto-initialization.
+
+    ``MT5Client.from_connected_client()`` accepts any raw client object without
+    validating that it is already connected. pdmt5's ``account_info()``/``login()``
+    silently call ``initialize()`` on an uninitialized client, so this guards the
+    guarantee that ``switch_account`` never (re)initializes the terminal.
+    """
+    mock_mt5 = ModuleType("mock_mt5")
+    mock_mt5.initialize = MagicMock()  # type: ignore[attr-defined]
+    raw_client = Mt5DataClient(mt5=mock_mt5)
+    client = MT5Client.from_connected_client(raw_client)
+
+    with pytest.raises(Mt5ConnectionError, match="active persistent session"):
+        switch_account(client, login=222)
+
+    mock_mt5.initialize.assert_not_called()  # type: ignore[attr-defined]
+
+
+def test_switch_account_normalizes_login_failure() -> None:
+    """A failed MT5 login becomes the stable connection exception."""
+    raw_client = MagicMock()
+    raw_client.account_info.return_value = SimpleNamespace(login=111, server="Demo")
+    raw_client.login.return_value = False
+    raw_client.last_error.return_value = (-6, "authorization failed")
+    client = _connected_client(raw_client)
+
+    with pytest.raises(Mt5ConnectionError, match="authorization failed"):
+        switch_account(client, login=222, server="Demo")
+
+
+def test_switch_account_normalizes_runtime_error() -> None:
+    """Underlying pdmt5 runtime errors use the stable connection exception.
+
+    This also covers the no-active-account case: pdmt5's
+    ``Mt5DataClient.account_info()`` raises ``Mt5RuntimeError`` rather than
+    returning ``None`` when MT5 has no active account, so ``switch_account``
+    requires an already-active account and surfaces that failure the same way
+    as any other runtime error.
+    """
+    raw_client = MagicMock()
+    raw_client.account_info.side_effect = Mt5RuntimeError("connection lost")
+    client = _connected_client(raw_client)
+
+    with pytest.raises(Mt5ConnectionError, match="connection lost"):
+        switch_account(client, login=222, server="Demo")
+
+
+def test_switch_account_fails_if_requested_account_is_not_active_after_login() -> None:
+    """A successful login return cannot bypass active-account verification."""
+    raw_client = MagicMock()
+    raw_client.account_info.side_effect = [
+        SimpleNamespace(login=111, server="Demo"),
+        SimpleNamespace(login=222, server="Other"),
+    ]
+    raw_client.login.return_value = True
+    client = _connected_client(raw_client)
+
+    with pytest.raises(Mt5ConnectionError, match="did not activate"):
+        switch_account(client, login=222, server="Demo")

{mt5cli-1.4.2 → mt5cli-1.5.0}/uv.lock

@@ -595,7 +595,7 @@ wheels = [
 
 [[package]]
 name = "mt5cli"
-version = "1.4.2"
+version = "1.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "pandas" },

mt5cli-1.4.2/AGENTS.md

@@ -1,29 +0,0 @@
-# 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.2/CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md