mt5api 0.1.0__tar.gz → 0.2.0__tar.gz

{mt5api-0.1.0 → mt5api-0.2.0}/.agents/skills/local-qa/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: local-qa
 description: Run local QA including formatting, linting, and testing for the repository. Use whenever any file has been updated.
-disable-model-invocation: true
+disable-model-invocation: false
 ---
 
 # Local QA (format, lint, and test)

{mt5api-0.1.0 → mt5api-0.2.0}/.agents/skills/local-qa/scripts/qa.sh

@@ -10,7 +10,7 @@ uv run pyright .
 uv run pytest
 
 # Markdown
-npx prettier --write './**/*.md'
+npx -y prettier --write './**/*.md'
 
 # GitHub Actions
 case "${OSTYPE}" in

{mt5api-0.1.0 → mt5api-0.2.0}/.agents/skills/mt5api/SKILL.md

@@ -3,8 +3,8 @@ name: mt5api
 description: >-
   Query the MT5 API for account info, terminal status, health checks, symbol
   data, market data (OHLCV rates, ticks, market depth), open positions, pending
-  orders, and trade history. Use when the user wants to interact with any mt5api
-  endpoint.
+  orders, trade history, and reconnecting the MT5 terminal with new
+  credentials. Use when the user wants to interact with any mt5api endpoint.
 allowed-tools: Bash
 ---
 
@@ -30,6 +30,16 @@ if [ -n "${MT5API_SECRET_KEY:-}" ]; then
 fi
 ```
 
+Login credentials for `/connection/login` are read from the environment so
+the password is never hard-coded in a command:
+
+| Variable          | Description                                | Required for login |
+| ----------------- | ------------------------------------------ | ------------------ |
+| `MT5API_LOGIN`    | Trading account login (integer)            | yes                |
+| `MT5API_PASSWORD` | Trading account password                   | yes                |
+| `MT5API_SERVER`   | Trading server name (e.g., `Broker-Demo`)  | yes                |
+| `MT5API_TIMEOUT`  | Connection timeout in milliseconds (`> 0`) | no                 |
+
 ## Response Formats
 
 All endpoints (except `/health`) return JSON by default. Request Parquet with
@@ -44,6 +54,11 @@ All endpoints (except `/health`) return JSON by default. Request Parquet with
   symbol or skipping DOM data.
 - Empty arrays from `/positions`, `/orders`, `/history/orders`, or
   `/history/deals` are valid results.
+- `/connection/login` reconnects the shared MT5 client to a different account.
+  It shuts down the current connection and releases any active market-book
+  subscriptions before logging in. Never echo the password back to the user
+  and do not log it; the response only confirms `login`, `server`, `timeout`,
+  and `connected`.
 
 ---
 
@@ -77,6 +92,59 @@ curl -s "${AUTH_HEADER[@]}" \
 
 ---
 
+## Connection
+
+### Reconnect to MT5
+
+Shut down the current MT5 client and reconnect with new credentials. Active
+market-book subscriptions are released first. The call is serialized so
+concurrent reconnect attempts do not race. The password is sent only in the
+request body and is never echoed in the response.
+
+```bash
+# Build JSON body from env vars; include timeout only when set
+LOGIN_BODY=$(python3 -c "
+import json, os, sys
+body = {
+    'login': int(os.environ['MT5API_LOGIN']),
+    'password': os.environ['MT5API_PASSWORD'],
+    'server': os.environ['MT5API_SERVER'],
+}
+t = os.environ.get('MT5API_TIMEOUT')
+if t:
+    body['timeout'] = int(t)
+print(json.dumps(body))
+")
+curl -s -X POST "${AUTH_HEADER[@]}" \
+  -H 'Content-Type: application/json' \
+  -d "${LOGIN_BODY}" \
+  "${MT5API_URL}/connection/login" | python -m json.tool
+```
+
+Request body:
+
+| Field    | Type   | Required | Description                                |
+| -------- | ------ | -------- | ------------------------------------------ |
+| login    | int    | yes      | Trading account login (positive integer)   |
+| password | string | yes      | Trading account password (never echoed)    |
+| server   | string | yes      | Trading server name (e.g., `Broker-Demo`)  |
+| timeout  | int    | no       | Connection timeout in milliseconds (`> 0`) |
+
+Successful response (`200`):
+
+| Field     | Type   | Description                                  |
+| --------- | ------ | -------------------------------------------- |
+| login     | int    | Login that was used to connect               |
+| server    | string | Trading server that was connected to         |
+| timeout   | int?   | Timeout in milliseconds if one was specified |
+| connected | bool   | `true` when the new connection succeeded     |
+
+On failure, MT5 errors surface as `503 Service Unavailable` with an RFC 7807
+problem-details body. Never include the supplied password in any summary or
+diagnostic you return to the user.
+
+---
+
 ## Account & Terminal
 
 ### Account Info
@@ -323,3 +391,6 @@ Either `(date_from AND date_to)` or `(ticket OR position)` must be provided.
    running or reachable.
 9. For historical queries, remind the user that either a date range or a
    ticket/position filter is required.
+10. For `/connection/login`, always send the password in the POST body and
+    never repeat it in any reply or log message. If the user asks you to
+    reconnect, confirm the target `login`/`server` before sending the request.

{mt5api-0.1.0 → mt5api-0.2.0}/.github/workflows/ci.yml

@@ -19,7 +19,6 @@ on:
         options:
           - lint-and-test
           - docs-deploy
-          - release
         description: Choose the workflow to run
         default: lint-and-test
 permissions:
@@ -54,10 +53,7 @@ jobs:
   python-docs-deploy:
     if: >
       github.event_name == 'push'
-      || (
-        github.event_name == 'workflow_dispatch'
-        && (inputs.workflow == 'docs-deploy' || inputs.workflow == 'release')
-      )
+      || (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]
@@ -66,23 +62,6 @@ jobs:
       runs-on: ubuntu-slim
     secrets:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  python-package-release:
-    if: >
-      github.event_name == 'push'
-      || (
-        github.event_name == 'workflow_dispatch'
-        && (inputs.workflow == 'release' || inputs.workflow == 'lint-and-test')
-      )
-    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]
-    with:
-      package-path: .
-      create-releases: ${{ github.event_name == 'workflow_dispatch' && inputs.workflow == 'release' }}
-    secrets:
-      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   dependabot-auto-merge:
     if: >
       github.event_name == 'pull_request' && github.actor == 'dependabot[bot]'

mt5api-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+---
+name: Release
+on:
+  workflow_dispatch:
+permissions:
+  contents: read
+defaults:
+  run:
+    shell: bash -euo pipefail {0}
+    working-directory: .
+jobs:
+  build-and-release:
+    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]
+    with:
+      package-path: .
+      create-github-release: true
+      publish-to-pypi: false
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  publish-to-pypi:
+    name: Publish the Python 🐍 distribution 📦 to PyPI
+    if: >
+      startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build-and-release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ needs.build-and-release.outputs.project-name }}
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          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
+        with:
+          verbose: true

{mt5api-0.1.0 → mt5api-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5api
-Version: 0.1.0
+Version: 0.2.0
 Summary: MetaTrader 5 REST API
 Project-URL: Repository, https://github.com/dceoy/mt5api.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -89,6 +89,20 @@ graph TB
 
 Install and run the API on the Windows machine where MetaTrader 5 is installed.
 
+Install the latest release from PyPI:
+
+```console
+pip install mt5api
+```
+
+Or, when managing the project with `uv`, add it as a dependency:
+
+```console
+uv add mt5api
+```
+
+Alternatively, install from source:
+
 ```powershell
 git clone https://github.com/dceoy/mt5api.git
 cd mt5api
@@ -97,12 +111,24 @@ uv sync
 
 ## Running the API on Windows
 
+After installing from PyPI:
+
 ```powershell
 $env:MT5API_SECRET_KEY = "your-secret-api-key"  # Optional: omit to disable auth
 $env:MT5API_ROUTER_PREFIX = "/api/v1"     # Optional: omit for root-level routes
-uv run uvicorn mt5api.main:app --host 0.0.0.0 --port 8000
+python -m mt5api
 ```
 
+`python -m mt5api` reads `MT5API_HOST`, `MT5API_PORT`, and `MT5API_LOG_LEVEL`
+from the environment. You can also invoke `uvicorn` directly:
+
+```powershell
+uvicorn mt5api.main:app --host 0.0.0.0 --port 8000
+```
+
+If you cloned the source tree, prepend `uv run` to either command (for example,
+`uv run uvicorn mt5api.main:app --host 0.0.0.0 --port 8000`).
+
 Docs:
 
 - Swagger UI: `http://localhost:8000/docs`

{mt5api-0.1.0 → mt5api-0.2.0}/README.md

@@ -60,6 +60,20 @@ graph TB
 
 Install and run the API on the Windows machine where MetaTrader 5 is installed.
 
+Install the latest release from PyPI:
+
+```console
+pip install mt5api
+```
+
+Or, when managing the project with `uv`, add it as a dependency:
+
+```console
+uv add mt5api
+```
+
+Alternatively, install from source:
+
 ```powershell
 git clone https://github.com/dceoy/mt5api.git
 cd mt5api
@@ -68,12 +82,24 @@ uv sync
 
 ## Running the API on Windows
 
+After installing from PyPI:
+
 ```powershell
 $env:MT5API_SECRET_KEY = "your-secret-api-key"  # Optional: omit to disable auth
 $env:MT5API_ROUTER_PREFIX = "/api/v1"     # Optional: omit for root-level routes
-uv run uvicorn mt5api.main:app --host 0.0.0.0 --port 8000
+python -m mt5api
 ```
 
+`python -m mt5api` reads `MT5API_HOST`, `MT5API_PORT`, and `MT5API_LOG_LEVEL`
+from the environment. You can also invoke `uvicorn` directly:
+
+```powershell
+uvicorn mt5api.main:app --host 0.0.0.0 --port 8000
+```
+
+If you cloned the source tree, prepend `uv run` to either command (for example,
+`uv run uvicorn mt5api.main:app --host 0.0.0.0 --port 8000`).
+
 Docs:
 
 - Swagger UI: `http://localhost:8000/docs`

{mt5api-0.1.0 → mt5api-0.2.0}/docs/api/rest-api.md

@@ -116,9 +116,9 @@ If `MT5API_ROUTER_PREFIX` is configured, prepend it to each API route below.
 - `GET /rates/range` (`symbol`, `timeframe`, `date_from`, `date_to`, `format`)
 - `GET /ticks/from` (`symbol`, `date_from`, `count`, `flags`, `format`)
 - `GET /ticks/range` (`symbol`, `date_from`, `date_to`, `flags`, `format`)
-- `GET /market-book/{symbol}` (`format`) — Market depth (DOM) *(experimental)*
-- `POST /market-book/{symbol}/subscribe` — Subscribe to DOM events *(experimental)*
-- `POST /market-book/{symbol}/unsubscribe` — Unsubscribe from DOM events *(experimental)*
+- `GET /market-book/{symbol}` (`format`) — Market depth (DOM) _(experimental)_
+- `POST /market-book/{symbol}/subscribe` — Subscribe to DOM events _(experimental)_
+- `POST /market-book/{symbol}/unsubscribe` — Unsubscribe from DOM events _(experimental)_
 
 ### Calculations
 
@@ -162,6 +162,14 @@ structure](https://www.mql5.com/en/docs/constants/structures/mqltraderequest),
 with typed validation for core fields such as `action`, `symbol`, `volume`,
 `type`, and `price`.
 
+### Connection
+
+- `POST /connection/login` (body: `{"login": ..., "password": "...",
+"server": "...", "timeout": ...}`) — Reconnect the MT5 terminal with the
+  supplied credentials. Any active market-book subscriptions are released and
+  the previous MT5 client is shut down before the new connection is
+  established. The supplied password is never echoed in responses or logs.
+
 ## Response Formatter Utilities
 
 If you are extending the API with custom endpoints, use the formatter helpers
@@ -291,6 +299,14 @@ curl -X POST -H "X-API-Key: your-secret-api-key" -H "Content-Type: application/j
   "http://windows-host:8000/order/check"
 ```
 
+### Reconnect to MT5
+
+```console
+curl -X POST -H "X-API-Key: your-secret-api-key" -H "Content-Type: application/json" \
+  -d '{"login": 12345678, "password": "s3cret", "server": "MetaQuotes-Demo", "timeout": 60000}' \
+  "http://windows-host:8000/connection/login"
+```
+
 ## Error Responses
 
 Errors follow RFC 7807 Problem Details:

mt5api-0.2.0/mt5api/dependencies.py

@@ -0,0 +1,236 @@
+"""FastAPI dependency injection for MT5 client and format negotiation."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Annotated, Any, TypeVar
+
+from fastapi import Header, Query, Request
+from pdmt5.dataframe import Mt5Config, Mt5DataClient
+
+from .constants import (
+    ACTIVE_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY,
+    MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY,
+)
+from .models import ResponseFormat
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+
+# Type variable for return types
+T = TypeVar("T")
+
+# Global singleton instance
+_mt5_client: Mt5DataClient | None = None
+
+# Serializes singleton replacement across concurrent reconnect requests.
+_mt5_client_lock = asyncio.Lock()
+
+
+def get_mt5_client_lock() -> asyncio.Lock:
+    """Return the lock guarding MT5 client singleton replacement."""
+    return _mt5_client_lock
+
+
+def get_mt5_client() -> Mt5DataClient:
+    """Get or create Mt5DataClient singleton instance.
+
+    This dependency provides a single shared MT5 client instance across all
+    requests to avoid multiple terminal connections.
+
+    Returns:
+        Mt5DataClient: Singleton MT5 client instance.
+
+    Raises:
+        RuntimeError: If MT5 client cannot be initialized.
+    """
+    global _mt5_client  # noqa: PLW0603
+
+    if _mt5_client is None:
+        config = Mt5Config()
+        _mt5_client = Mt5DataClient(config=config)
+        try:
+            _mt5_client.initialize_and_login_mt5()
+        except Exception as e:
+            _mt5_client = None
+            error_message = f"Failed to initialize MT5 client: {e!s}"
+            raise RuntimeError(error_message) from e
+
+    return _mt5_client
+
+
+def shutdown_mt5_client() -> None:
+    """Shutdown and cleanup MT5 client singleton.
+
+    This should be called during application shutdown to properly
+    close the MT5 connection.
+    """
+    global _mt5_client  # noqa: PLW0603
+
+    if _mt5_client is not None:
+        _mt5_client.shutdown()
+        _mt5_client = None
+
+
+async def replace_mt5_client(config: Mt5Config) -> Mt5DataClient:
+    """Swap the MT5 client singleton with a new connection.
+
+    Constructs and initializes the new ``Mt5DataClient`` BEFORE touching the
+    singleton so a failed reconnect leaves the existing client in place
+    instead of disconnecting the operator from a working terminal. The new
+    client is installed atomically; the old client (if any) is shut down on
+    a best-effort basis after the swap. Callers MUST hold
+    ``get_mt5_client_lock`` so concurrent reconnect requests do not race.
+
+    The raised ``RuntimeError`` deliberately omits the underlying exception
+    text from its message because third-party ``pdmt5``/MetaTrader5
+    exceptions may include the connection config (and thus the password) in
+    their string form. The original exception is chained via ``raise from``
+    and logged server-side so diagnostics are preserved.
+
+    Args:
+        config: Configuration for the new MT5 connection.
+
+    Returns:
+        The newly initialized MT5 data client.
+
+    Raises:
+        RuntimeError: If the new MT5 client cannot be constructed or
+            initialized. The previously installed client is preserved.
+    """
+    global _mt5_client  # noqa: PLW0603
+
+    try:
+        new_client = Mt5DataClient(config=config)
+        await asyncio.to_thread(new_client.initialize_and_login_mt5)
+    except Exception as e:
+        logger.exception("Failed to initialize MT5 client")
+        error_message = "Failed to initialize MT5 client"
+        raise RuntimeError(error_message) from e
+
+    old_client = _mt5_client
+    _mt5_client = new_client
+
+    if old_client is not None:
+        try:
+            await asyncio.to_thread(old_client.shutdown)
+        except Exception:
+            logger.exception("Failed to shutdown previous MT5 client")
+
+    return new_client
+
+
+async def release_market_book_subscriptions(app: FastAPI) -> None:
+    """Release tracked market-book subscriptions on the application.
+
+    Iterates the application's tracked subscription set, calls
+    ``market_book_release`` for each symbol using the cleanup client, then
+    clears the tracking state. Individual release failures are logged and do
+    not stop processing.
+
+    Args:
+        app: FastAPI application whose state holds the subscription set.
+    """
+    subscriptions = getattr(
+        app.state,
+        ACTIVE_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY,
+        None,
+    )
+    if not isinstance(subscriptions, set) or not subscriptions:
+        return
+
+    mt5_client = getattr(app.state, MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY, None)
+    if mt5_client is None:
+        logger.warning("Active market-book subscriptions found without cleanup client")
+        subscriptions.clear()
+        setattr(app.state, MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY, None)
+        return
+
+    def release_subscriptions() -> None:
+        for symbol in tuple(subscriptions):
+            try:
+                mt5_client.market_book_release(symbol=symbol)
+            except Exception:
+                logger.exception("Failed to release market book for %s", symbol)
+
+    await asyncio.to_thread(release_subscriptions)
+
+    subscriptions.clear()
+    setattr(app.state, MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY, None)
+
+
+async def run_in_threadpool(
+    func: Callable[..., T],
+    *args: Any,  # noqa: ANN401
+    **kwargs: Any,  # noqa: ANN401
+) -> T:
+    """Run synchronous MT5 function in thread pool.
+
+    MT5 API calls are synchronous and blocking. This wrapper runs them
+    in a thread pool to avoid blocking the async event loop.
+
+    Args:
+        func: Synchronous function to run.
+        *args: Positional arguments for the function.
+        **kwargs: Keyword arguments for the function.
+
+    Returns:
+        The function's return value.
+    """
+    return await asyncio.to_thread(func, *args, **kwargs)
+
+
+def get_response_format(
+    accept: Annotated[str | None, Header()] = None,
+    format_param: Annotated[ResponseFormat | None, Query(alias="format")] = None,
+) -> ResponseFormat:
+    """Determine response format from Accept header or query parameter.
+
+    Priority:
+    1. Query parameter (?format=json or ?format=parquet)
+    2. Accept header (application/json or application/parquet)
+    3. Default to JSON
+
+    Args:
+        accept: Accept header from request.
+        format_param: Format query parameter.
+
+    Returns:
+        ResponseFormat: Negotiated response format.
+    """
+    # Query parameter takes priority
+    if format_param is not None:
+        return format_param
+
+    # Check Accept header
+    if accept:
+        accept_lower = accept.lower()
+        if "application/parquet" in accept_lower:
+            return ResponseFormat.PARQUET
+        if "application/json" in accept_lower:
+            return ResponseFormat.JSON
+
+    # Default to JSON
+    return ResponseFormat.JSON
+
+
+def get_request_info(request: Request) -> dict[str, Any]:
+    """Extract request information for logging.
+
+    Args:
+        request: FastAPI request object.
+
+    Returns:
+        Dictionary with request details.
+    """
+    return {
+        "method": request.method,
+        "url": str(request.url),
+        "client": request.client.host if request.client else None,
+        "user_agent": request.headers.get("user-agent"),
+    }

{mt5api-0.1.0 → mt5api-0.2.0}/mt5api/main.py

@@ -29,9 +29,18 @@ from .constants import (
     MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY,
     MAX_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY,
 )
-from .dependencies import run_in_threadpool, shutdown_mt5_client
+from .dependencies import release_market_book_subscriptions, shutdown_mt5_client
 from .middleware import add_middleware
-from .routers import account, calc, health, history, market, symbols, trading
+from .routers import (
+    account,
+    calc,
+    connection,
+    health,
+    history,
+    market,
+    symbols,
+    trading,
+)
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator
@@ -122,33 +131,6 @@ _configure_logging()
 logger = logging.getLogger(__name__)
 
 
-async def _release_market_book_subscriptions(app: FastAPI) -> None:
-    """Release active market-book subscriptions before shutting down MT5."""
-    subscriptions = getattr(
-        app.state,
-        ACTIVE_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY,
-        None,
-    )
-    if not isinstance(subscriptions, set) or not subscriptions:
-        return
-
-    mt5_client = getattr(app.state, MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY, None)
-    if mt5_client is None:
-        logger.warning("Active market-book subscriptions found without cleanup client")
-        subscriptions.clear()
-        setattr(app.state, MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY, None)
-        return
-
-    for symbol in tuple(sorted(subscriptions)):
-        try:
-            await run_in_threadpool(mt5_client.market_book_release, symbol=symbol)
-        except Exception:
-            logger.exception("Failed to release market book for %s", symbol)
-
-    subscriptions.clear()
-    setattr(app.state, MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY, None)
-
-
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     """Manage application lifespan (startup and shutdown).
@@ -178,7 +160,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     # Shutdown
     logger.info("Shutting down MT5 REST API...")
     try:
-        await _release_market_book_subscriptions(app)
+        await release_market_book_subscriptions(app)
     finally:
         shutdown_mt5_client()
     logger.info("MT5 connection closed")
@@ -208,5 +190,6 @@ app.include_router(account.router, prefix=router_prefix)
 app.include_router(history.router, prefix=router_prefix)
 app.include_router(calc.router, prefix=router_prefix)
 app.include_router(trading.router, prefix=router_prefix)
+app.include_router(connection.router, prefix=router_prefix)
 
 logger.info("MT5 REST API initialized")