mt5api 1.0.3__tar.gz → 1.0.4__tar.gz

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

@@ -9,6 +9,7 @@ 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.3 → mt5api-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5api
-Version: 1.0.3
+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>

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

@@ -166,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.3 → mt5api-1.0.4}/mt5api/constants.py

@@ -15,9 +15,7 @@ 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)