mt5api 1.0.3__tar.gz → 1.0.5__tar.gz

{mt5api-1.0.3 → mt5api-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5api
-Version: 1.0.3
+Version: 1.0.5
 Summary: MetaTrader 5 REST API
 Project-URL: Repository, https://github.com/dceoy/mt5api.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -21,7 +21,6 @@ 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
 

{mt5api-1.0.3 → mt5api-1.0.5}/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.5/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.5/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)

{mt5api-1.0.3 → mt5api-1.0.5}/mt5api/main.py

@@ -2,11 +2,10 @@
 
 from __future__ import annotations
 
-import asyncio
 import json
 import logging
 from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 from fastapi import FastAPI
 from fastapi.openapi.utils import get_openapi
@@ -18,7 +17,6 @@ from .config import (
     get_configured_python_log_level,
 )
 from .constants import (
-    ACTIVE_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY,
     API_DESCRIPTION,
     API_DOCS_URL,
     API_KEY_SECURITY_SCHEME_NAME,
@@ -26,10 +24,12 @@ from .constants import (
     API_REDOC_URL,
     API_TITLE,
     API_VERSION,
-    MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY,
-    MAX_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY,
 )
-from .dependencies import release_market_book_subscriptions, shutdown_mt5_client
+from .dependencies import (
+    initialize_mt5_runtime_state,
+    release_market_book_subscriptions,
+    shutdown_mt5_client,
+)
 from .middleware import add_middleware
 from .models import ErrorResponse
 from .routers import (
@@ -44,7 +44,14 @@ from .routers import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncGenerator
+    from collections.abc import AsyncGenerator, Iterator
+
+
+def _as_dict(value: object) -> dict[str, Any] | None:
+    """Return a typed dictionary after checking a dynamic OpenAPI value."""
+    if not isinstance(value, dict):
+        return None
+    return cast("dict[str, Any]", value)
 
 
 class _JsonFormatter(logging.Formatter):
@@ -57,52 +64,70 @@ class _JsonFormatter(logging.Formatter):
             "logger": record.name,
             "message": record.getMessage(),
         }
-
         if record.exc_info:
             payload["exception"] = self.formatException(record.exc_info)
-
         return json.dumps(payload)
 
 
 def _configure_logging() -> None:
     """Configure structured logging for the API."""
     log_level = get_configured_python_log_level()
-
     handler = logging.StreamHandler()
     handler.setFormatter(_JsonFormatter())
-
     root_logger = logging.getLogger()
     root_logger.handlers.clear()
     root_logger.setLevel(log_level)
     root_logger.addHandler(handler)
 
 
+def _iter_openapi_operations(
+    openapi_schema: dict[str, Any],
+) -> Iterator[dict[str, Any]]:
+    """Yield operation mappings from an OpenAPI schema.
+
+    Yields:
+        Individual HTTP operation mappings.
+    """
+    paths = _as_dict(openapi_schema.get("paths", {}))
+    if paths is None:
+        return
+    for methods_value in paths.values():
+        methods = _as_dict(methods_value)
+        if methods is None:
+            continue
+        for operation_value in methods.values():
+            operation = _as_dict(operation_value)
+            if operation is not None:
+                yield operation
+
+
 def _strip_auth_from_openapi(openapi_schema: dict[str, Any]) -> None:
     """Remove API key requirements from OpenAPI when auth is disabled."""
     openapi_schema.pop("security", None)
-
-    components = openapi_schema.get("components", {})
-    security_schemes = components.get("securitySchemes", {})
-    security_schemes.pop(API_KEY_SECURITY_SCHEME_NAME, None)
-    if not security_schemes:
-        components.pop("securitySchemes", None)
-
-    for methods in openapi_schema.get("paths", {}).values():
-        for operation in methods.values():
-            if isinstance(operation, dict):
-                operation.pop("security", None)
+    components = _as_dict(openapi_schema.get("components", {}))
+    if components is not None:
+        security_schemes = _as_dict(components.get("securitySchemes", {}))
+        if security_schemes is not None:
+            security_schemes.pop(API_KEY_SECURITY_SCHEME_NAME, None)
+            if not security_schemes:
+                components.pop("securitySchemes", None)
+    for operation in _iter_openapi_operations(openapi_schema):
+        operation.pop("security", None)
 
 
 def _patch_validation_error_responses(openapi_schema: dict[str, Any]) -> None:
     """Advertise RFC 7807 Problem Details for request validation failures."""
-    components = openapi_schema.setdefault("components", {})
-    schemas = components.setdefault("schemas", {})
+    components = _as_dict(openapi_schema.setdefault("components", {}))
+    if components is None:
+        return
+    schemas = _as_dict(components.setdefault("schemas", {}))
+    if schemas is None:
+        return
     schemas["ErrorResponse"] = ErrorResponse.model_json_schema(
         ref_template="#/components/schemas/{model}",
     )
     schemas.pop("HTTPValidationError", None)
     schemas.pop("ValidationError", None)
-
     error_response = {
         "description": "Validation Error",
         "content": {
@@ -111,22 +136,57 @@ def _patch_validation_error_responses(openapi_schema: dict[str, Any]) -> None:
             },
         },
     }
+    for operation in _iter_openapi_operations(openapi_schema):
+        responses = operation.get("responses")
+        responses = _as_dict(
+            cast("object", responses),  # pyright: ignore[reportUnknownArgumentType]
+        )
+        if responses is not None and "422" in responses:
+            responses["422"] = error_response
+
+
+def _supports_format_query(operation: dict[str, Any]) -> bool:
+    """Return whether an OpenAPI operation exposes the shared format query."""
+    parameters = operation.get("parameters", [])
+    if not isinstance(parameters, list):
+        return False
+    parameters = cast("list[object]", parameters)
+    return any(
+        (parameter := _as_dict(parameter_value)) is not None
+        and parameter.get("in") == "query"
+        and parameter.get("name") == "format"
+        for parameter_value in parameters
+    )
+
 
-    for methods in openapi_schema.get("paths", {}).values():
-        for operation in methods.values():
-            if isinstance(operation, dict) and "422" in operation.get("responses", {}):
-                operation["responses"]["422"] = error_response
+def _patch_parquet_success_responses(openapi_schema: dict[str, Any]) -> None:
+    """Advertise Parquet for operations using the shared format dependency."""
+    parquet_schema = {"schema": {"type": "string", "format": "binary"}}
+    for operation in _iter_openapi_operations(openapi_schema):
+        if not _supports_format_query(operation):
+            continue
+        responses = operation.get("responses")
+        responses = _as_dict(
+            cast("object", responses),  # pyright: ignore[reportUnknownArgumentType]
+        )
+        if responses is None:
+            continue
+        success = _as_dict(responses.get("200"))
+        if success is None:
+            continue
+        content = _as_dict(success.setdefault("content", {}))
+        if content is not None:
+            content.setdefault("application/parquet", parquet_schema)
 
 
 def _build_openapi_schema(app: FastAPI) -> dict[str, Any]:
     """Build OpenAPI schema for the current authentication mode.
 
     Returns:
-        OpenAPI schema for the current auth configuration.
+        Cached or newly generated OpenAPI schema.
     """
     if app.openapi_schema:
         return app.openapi_schema
-
     openapi_schema = get_openapi(
         title=app.title,
         version=app.version,
@@ -136,7 +196,7 @@ def _build_openapi_schema(app: FastAPI) -> dict[str, Any]:
     if not is_auth_enabled():
         _strip_auth_from_openapi(openapi_schema)
     _patch_validation_error_responses(openapi_schema)
-
+    _patch_parquet_success_responses(openapi_schema)
     app.openapi_schema = openapi_schema
     return openapi_schema
 
@@ -145,7 +205,7 @@ def _custom_openapi() -> dict[str, Any]:
     """Build OpenAPI schema for the current application instance.
 
     Returns:
-        OpenAPI schema for the application.
+        Cached or newly generated OpenAPI schema.
     """
     return _build_openapi_schema(app)
 
@@ -156,40 +216,25 @@ logger = logging.getLogger(__name__)
 
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
-    """Manage application lifespan (startup and shutdown).
-
-    Args:
-        app: FastAPI application instance (unused but required by FastAPI).
+    """Manage application startup and shutdown.
 
     Yields:
-        None
+        Control to FastAPI while the application is running.
     """
-    # Startup
     logger.info("Starting MT5 REST API...")
-    setattr(app.state, ACTIVE_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY, set())
-    setattr(app.state, MARKET_BOOK_CLEANUP_CLIENT_STATE_KEY, None)
-    setattr(
-        app.state,
-        MAX_MARKET_BOOK_SUBSCRIPTIONS_STATE_KEY,
-        get_configured_max_market_book_subscriptions(),
+    state = initialize_mt5_runtime_state(
+        app,
+        max_market_book_subscriptions=get_configured_max_market_book_subscriptions(),
     )
-
-    # Note: MT5 client is initialized lazily on first request via dependency
-    # This avoids blocking startup if MT5 is not available
-    await asyncio.sleep(0)  # Make function truly async
-
     yield
-
-    # Shutdown
     logger.info("Shutting down MT5 REST API...")
     try:
-        await release_market_book_subscriptions(app)
+        await release_market_book_subscriptions(state)
     finally:
-        shutdown_mt5_client()
+        shutdown_mt5_client(state)
     logger.info("MT5 connection closed")
 
 
-# Create FastAPI application
 app = FastAPI(
     title=API_TITLE,
     description=API_DESCRIPTION,
@@ -200,11 +245,8 @@ app = FastAPI(
     openapi_url=API_OPENAPI_URL,
 )
 app.openapi = _custom_openapi
-
-# Add middleware
 add_middleware(app)
 
-# Include routers
 router_prefix = get_configured_api_router_prefix()
 app.include_router(health.router, prefix=router_prefix)
 app.include_router(symbols.router, prefix=router_prefix)