mt5api 1.0.2__tar.gz → 1.0.4__tar.gz

{mt5api-1.0.2 → mt5api-1.0.4}/.agents/skills/local-qa/scripts/qa.sh

@@ -3,7 +3,13 @@
 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 .

mt5api-1.0.4/.github/CODEOWNERS

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

{mt5api-1.0.2 → mt5api-1.0.4}/.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,7 +46,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-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
@@ -56,7 +56,7 @@ jobs:
       || (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
@@ -71,7 +71,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"]
@@ -81,7 +81,7 @@ 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]
+    uses: dceoy/gha-for-devops/.github/workflows/dependabot-auto-merge.yml@main  # zizmor: ignore[unpinned-uses]
     permissions:
       contents: write
       pull-requests: write

{mt5api-1.0.2 → mt5api-1.0.4}/.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 }}

{mt5api-1.0.2 → mt5api-1.0.4}/.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

mt5api-1.0.4/AGENTS.md

@@ -0,0 +1,38 @@
+# Repository Guidelines
+
+## Build, Test, and Development Commands
+
+- `.agents/skills/local-qa/scripts/qa.sh`: run the repository QA workflow after
+  any file update. This wraps formatting, linting, type checks, tests, Markdown
+  formatting, and workflow/security checks.
+
+The API server runtime requires Windows with MetaTrader 5 installed and logged
+in. Non-Windows systems are suitable for editing docs and most mocked tests.
+
+## Testing Guidelines
+
+Parametrize unit tests with `pytest.mark.parametrize` when the same behavior
+should be verified across multiple input and expected-output cases. Prefer
+mocked MT5/pdmt5 interactions unless a test explicitly requires a Windows MT5
+terminal.
+
+## Design Principles
+
+Apply KISS, DRY, and YAGNI when changing code. Prefer the simplest direct
+implementation that satisfies the current requirement. Remove duplication when
+it improves clarity or prevents drift, but avoid abstractions that do not serve
+an immediate need. Keep changes small, focused, and easy to review.
+
+## Commit & Pull Request Guidelines
+
+Keep commits scoped to one logical change. Before committing or opening a PR,
+run `.agents/skills/local-qa/scripts/qa.sh`. Pull requests should describe the
+behavior change, list verification commands, link related issues when
+applicable, and call out any runtime impact for Windows/MT5 users.
+
+## Security & Configuration Tips
+
+Do not commit credentials, terminal account details, or real API keys. Configure
+runtime values through environment variables such as `MT5API_SECRET_KEY`,
+`MT5API_ROUTER_PREFIX`, `MT5API_HOST`, `MT5API_PORT`, and
+`MT5API_LOG_LEVEL`.

{mt5api-1.0.2 → mt5api-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5api
-Version: 1.0.2
+Version: 1.0.4
 Summary: MetaTrader 5 REST API
 Project-URL: Repository, https://github.com/dceoy/mt5api.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -15,11 +15,12 @@ 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: fastapi>=0.115.0
-Requires-Dist: httpx>=0.27.0
+Requires-Dist: pandas>=3.0.3
 Requires-Dist: pdmt5>=1.2.0
 Requires-Dist: pyarrow>=18.0.0
+Requires-Dist: pydantic>=2.13.4
 Requires-Dist: python-multipart>=0.0.31
 Requires-Dist: uvicorn[standard]>=0.32.0
 Description-Content-Type: text/markdown
@@ -85,7 +86,6 @@ graph TB
 
 ## Requirements
 
-- Python 3.11+
 - Windows host with MetaTrader 5 terminal installed and logged in
 - Linux and macOS are not supported for the API server runtime, but they work
   for HTTP clients

{mt5api-1.0.2 → mt5api-1.0.4}/README.md

@@ -59,7 +59,6 @@ graph TB
 
 ## Requirements
 
-- Python 3.11+
 - Windows host with MetaTrader 5 terminal installed and logged in
 - Linux and macOS are not supported for the API server runtime, but they work
   for HTTP clients

{mt5api-1.0.2 → mt5api-1.0.4}/docs/api/deployment.md

@@ -10,7 +10,6 @@ macOS because the `MetaTrader5` Python package is supported only on Windows.
 
 - Windows 10/11
 - MetaTrader 5 installed and logged in
-- Python 3.11+
 - `mt5api` installed
 - PowerShell access with permission to install and manage services
 

{mt5api-1.0.2 → mt5api-1.0.4}/docs/api/rest-api.md

@@ -10,7 +10,6 @@ system.
 
 ## Runtime Requirements
 
-- Python 3.11+
 - Windows host with MetaTrader 5 terminal installed and logged in
 - Linux and macOS are not supported for the API server runtime, but they work
   for HTTP clients
@@ -167,9 +166,12 @@ with typed validation for core fields such as `action`, `symbol`, `volume`,
 
 - `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.
+  supplied credentials. The replacement client is initialized and installed
+  before active market-book subscriptions are released and cleared. The old
+  wrapper is not shut down after a successful replacement because MetaTrader5
+  connection state is process-global; shutting it down could close the newly
+  established session. If replacement fails, existing subscription tracking is
+  preserved. The supplied password is never echoed in responses or logs.
 
 ## Response Formatter Utilities
 

{mt5api-1.0.2 → mt5api-1.0.4}/docs/index.md

@@ -26,7 +26,6 @@ system.
 
 ## Requirements
 
-- Python 3.11+
 - Windows OS with MetaTrader 5 terminal installed and logged in
 - Linux and macOS are not supported for the API server runtime, but they work
   for HTTP clients

{mt5api-1.0.2 → mt5api-1.0.4}/mt5api/constants.py

@@ -1,21 +1,21 @@
 """Application-wide constants."""
 
+from importlib.metadata import version
+
 API_TITLE = "MT5 REST API"
 API_DESCRIPTION = (
     "REST API for MetaTrader 5 data access and non-executing terminal utilities. "
     "Provides market data, account information, trading history, calculations, "
     "and safe operational endpoints via HTTP."
 )
-API_VERSION = "1.0.2"
+API_VERSION = version("mt5api")
 API_DOCS_URL = "/docs"
 API_REDOC_URL = "/redoc"
 API_OPENAPI_URL = "/openapi.json"
 API_APP_IMPORT = "mt5api.main:app"
 API_KEY_HEADER_NAME = "X-API-Key"
 API_KEY_SECURITY_SCHEME_NAME = "APIKeyHeader"
-ACTIVE_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY = "active_market_book_subscriptions"
-MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY = "market_book_cleanup_client"
-MAX_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY = "max_market_book_subscriptions"
+MT5_RUNTIME_STATE_KEY = "mt5_runtime"
 
 ENV_MT5API_HOST = "MT5API_HOST"
 ENV_MT5API_PORT = "MT5API_PORT"

mt5api-1.0.4/mt5api/dependencies.py

@@ -0,0 +1,210 @@
+"""FastAPI dependency injection for MT5 client and format negotiation."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Annotated, Any, TypeVar
+
+from fastapi import Header, Query, Request
+from pdmt5.dataframe import Mt5Config, Mt5DataClient
+
+from .config import get_configured_max_market_book_subscriptions
+from .constants import MT5_RUNTIME_STATE_KEY
+from .models import ResponseFormat
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class Mt5RuntimeState:
+    """Application-scoped owner for MT5 connection and subscription state."""
+
+    client: Mt5DataClient | None = None
+    client_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    market_book_subscriptions: set[str] = field(default_factory=set[str])
+    market_book_cleanup_client: Mt5DataClient | None = None
+    max_market_book_subscriptions: int = 0
+
+
+def initialize_mt5_runtime_state(
+    app: FastAPI,
+    *,
+    max_market_book_subscriptions: int | None = None,
+) -> Mt5RuntimeState:
+    """Create and install the application-scoped MT5 runtime state.
+
+    Args:
+        app: FastAPI application that owns the state.
+        max_market_book_subscriptions: Optional explicit subscription limit.
+
+    Returns:
+        Newly installed runtime state.
+    """
+    state = Mt5RuntimeState(
+        max_market_book_subscriptions=(
+            get_configured_max_market_book_subscriptions()
+            if max_market_book_subscriptions is None
+            else max_market_book_subscriptions
+        )
+    )
+    setattr(app.state, MT5_RUNTIME_STATE_KEY, state)
+    return state
+
+
+def get_mt5_runtime_state(request: Request) -> Mt5RuntimeState:
+    """Return the request application's MT5 runtime state.
+
+    Returns:
+        Existing state or a lazily installed state for direct ASGI usage.
+    """
+    state = getattr(request.app.state, MT5_RUNTIME_STATE_KEY, None)
+    if isinstance(state, Mt5RuntimeState):
+        return state
+    return initialize_mt5_runtime_state(request.app)
+
+
+def get_mt5_client_lock(request: Request) -> asyncio.Lock:
+    """Return the application-scoped MT5 replacement lock.
+
+    Returns:
+        Lock guarding client replacement and subscription cleanup.
+    """
+    return get_mt5_runtime_state(request).client_lock
+
+
+def get_mt5_client(request: Request) -> Mt5DataClient:
+    """Get or create the application-scoped MT5 client instance.
+
+    Args:
+        request: Request whose application owns the MT5 runtime state.
+
+    Returns:
+        Shared initialized MT5 data client.
+
+    Raises:
+        RuntimeError: If MT5 client initialization fails.
+    """
+    state = get_mt5_runtime_state(request)
+    if state.client is None:
+        client = Mt5DataClient(config=Mt5Config())
+        try:
+            client.initialize_and_login_mt5()
+        except Exception as exc:
+            error_message = f"Failed to initialize MT5 client: {exc!s}"
+            raise RuntimeError(error_message) from exc
+        state.client = client
+    return state.client
+
+
+def shutdown_mt5_client(state: Mt5RuntimeState) -> None:
+    """Shutdown and clear the application-scoped MT5 client."""
+    client = state.client
+    if client is None:
+        return
+    state.client = None
+    client.shutdown()
+
+
+async def replace_mt5_client(
+    state: Mt5RuntimeState,
+    config: Mt5Config,
+) -> Mt5DataClient:
+    """Replace the application's client after successful initialization.
+
+    MetaTrader5 connection state is process-global, so the previous wrapper is
+    not shut down after success because doing so could close the new session.
+
+    Returns:
+        Newly initialized and installed client.
+
+    Raises:
+        RuntimeError: If the replacement cannot be initialized.
+    """
+    try:
+        new_client = Mt5DataClient(config=config)
+        await asyncio.to_thread(new_client.initialize_and_login_mt5)
+    except Exception as exc:
+        logger.exception("Failed to initialize MT5 client")
+        error_message = "Failed to initialize MT5 client"
+        raise RuntimeError(error_message) from exc
+    state.client = new_client
+    return new_client
+
+
+async def release_market_book_subscriptions(state: Mt5RuntimeState) -> None:
+    """Release and clear all market-book subscriptions owned by ``state``."""
+    subscriptions = state.market_book_subscriptions
+    if not subscriptions:
+        state.market_book_cleanup_client = None
+        return
+    cleanup_client = state.market_book_cleanup_client
+    if cleanup_client is None:
+        logger.warning("Active market-book subscriptions found without cleanup client")
+        subscriptions.clear()
+        return
+
+    def release_subscriptions() -> None:
+        for symbol in tuple(subscriptions):
+            try:
+                cleanup_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()
+    state.market_book_cleanup_client = None
+
+
+async def run_in_threadpool(
+    func: Callable[..., T],
+    *args: Any,  # noqa: ANN401
+    **kwargs: Any,  # noqa: ANN401
+) -> T:
+    """Run a synchronous MT5 function without blocking the event loop.
+
+    Returns:
+        Result returned by ``func``.
+    """
+    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 query parameter or Accept header.
+
+    Returns:
+        Selected response format, defaulting to JSON.
+    """
+    if format_param is not None:
+        return format_param
+    if accept:
+        accept_lower = accept.lower()
+        if "application/parquet" in accept_lower:
+            return ResponseFormat.PARQUET
+        if "application/json" in accept_lower:
+            return ResponseFormat.JSON
+    return ResponseFormat.JSON
+
+
+def get_request_info(request: Request) -> dict[str, Any]:
+    """Extract request information for logging.
+
+    Returns:
+        Request method, URL, client address, and user agent.
+    """
+    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-1.0.4/mt5api/formatters.py

@@ -0,0 +1,163 @@
+"""Response formatters for JSON and Apache Parquet formats."""
+
+from __future__ import annotations
+
+import io
+from typing import TYPE_CHECKING, Any, cast, overload
+
+import pandas as pd
+import pyarrow as pa  # type: ignore[import-untyped]
+import pyarrow.parquet as pq  # type: ignore[import-untyped]
+from fastapi.responses import Response
+
+from .models import DataResponse, ResponseFormat
+
+_SUPPORTED_RESPONSE_FORMATS = {ResponseFormat.JSON, ResponseFormat.PARQUET}
+_INVALID_DATA_MESSAGE = "data must be a pandas DataFrame or dict[str, Any]"
+
+if TYPE_CHECKING:  # pragma: no cover
+    from typing import Protocol
+
+    class _PyArrowTable(Protocol):
+        """Structural type for the PyArrow table passed to Parquet output."""
+
+    class _PyArrowTableFactory(Protocol):
+        """Structural type for the supported PyArrow table factory API."""
+
+        @staticmethod
+        def from_pandas(
+            dataframe: pd.DataFrame,
+            *,
+            preserve_index: bool = True,
+        ) -> _PyArrowTable: ...
+
+    class _PyArrowModule(Protocol):
+        """Structural type for the supported PyArrow module API."""
+
+        Table: _PyArrowTableFactory
+
+    class _PyArrowParquetModule(Protocol):
+        """Structural type for the supported PyArrow Parquet API."""
+
+        def write_table(
+            self,
+            table: _PyArrowTable,
+            where: io.BytesIO,
+            *,
+            compression: str = "snappy",
+            use_dictionary: bool = True,
+            write_statistics: bool = True,
+        ) -> None: ...
+
+    @overload
+    def format_response(
+        data: pd.DataFrame,
+        response_format: ResponseFormat,
+    ) -> DataResponse | Response: ...
+
+    @overload
+    def format_response(
+        data: dict[str, Any],
+        response_format: ResponseFormat,
+    ) -> DataResponse | Response: ...
+
+
+def format_dataframe_to_json(
+    dataframe: pd.DataFrame,
+    *,
+    orient: str = "records",
+) -> DataResponse:
+    """Format DataFrame as JSON response.
+
+    Returns:
+        JSON data response.
+    """
+    if orient == "records":
+        data_value: list[dict[str, Any]] | dict[str, Any] = cast(
+            "list[dict[str, Any]] | dict[str, Any]",
+            dataframe.to_dict(orient=orient),  # type: ignore[arg-type]
+        )
+    else:
+        data_value = cast(
+            "list[dict[str, Any]] | dict[str, Any]",
+            dataframe.to_dict(orient=orient),  # type: ignore[arg-type]
+        )
+    return DataResponse(
+        data=data_value, count=len(dataframe), format=ResponseFormat.JSON
+    )
+
+
+def format_dict_to_json(data: dict[str, Any]) -> DataResponse:
+    """Format dictionary as JSON response.
+
+    Returns:
+        Single-record JSON data response.
+    """
+    return DataResponse(data=data, count=1, format=ResponseFormat.JSON)
+
+
+def format_dataframe_to_parquet(dataframe: pd.DataFrame) -> Response:
+    """Format DataFrame as a materialized Apache Parquet response.
+
+    Returns:
+        Binary Parquet HTTP response.
+    """
+    arrow_module = cast(
+        "_PyArrowModule",
+        pa,  # pyright: ignore[reportUnknownArgumentType]
+    )
+    parquet_module = cast(
+        "_PyArrowParquetModule",
+        pq,  # pyright: ignore[reportUnknownArgumentType]
+    )
+    table = arrow_module.Table.from_pandas(dataframe, preserve_index=False)
+    buffer = io.BytesIO()
+    parquet_module.write_table(
+        table,
+        buffer,
+        compression="snappy",
+        use_dictionary=True,
+        write_statistics=True,
+    )
+    return Response(
+        content=buffer.getvalue(),
+        media_type="application/parquet",
+        headers={"Content-Disposition": "attachment; filename=data.parquet"},
+    )
+
+
+def format_dict_to_parquet(data: dict[str, Any]) -> Response:
+    """Format a dictionary as a single-row Apache Parquet response.
+
+    Returns:
+        Binary Parquet HTTP response.
+    """
+    return format_dataframe_to_parquet(pd.DataFrame([data]))
+
+
+def format_response(
+    data: object,
+    response_format: ResponseFormat,
+) -> DataResponse | Response:
+    """Format a DataFrame or mapping as JSON or Parquet.
+
+    Returns:
+        JSON model or binary Parquet response.
+
+    Raises:
+        ValueError: If the response format is unsupported.
+        TypeError: If ``data`` is not a DataFrame or mapping.
+    """
+    if response_format not in _SUPPORTED_RESPONSE_FORMATS:
+        message = f"Unsupported response format: {response_format}"
+        raise ValueError(message)
+    if isinstance(data, pd.DataFrame):
+        if response_format == ResponseFormat.PARQUET:
+            return format_dataframe_to_parquet(data)
+        return format_dataframe_to_json(data)
+    if isinstance(data, dict):
+        data = cast("dict[str, Any]", data)
+        if response_format == ResponseFormat.PARQUET:
+            return format_dict_to_parquet(data)
+        return format_dict_to_json(data)
+    raise TypeError(_INVALID_DATA_MESSAGE)