mt5api 0.0.1__py3-none-any.whl

mt5api/__init__.py

@@ -0,0 +1,3 @@
+"""FastAPI-based REST API for MetaTrader 5 data access."""
+
+from __future__ import annotations

mt5api/__main__.py

@@ -0,0 +1,71 @@
+"""Module entrypoint for running the MT5 REST API."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import uvicorn
+
+_DEFAULT_HOST = "0.0.0.0"  # noqa: S104
+_DEFAULT_PORT = 8000
+_DEFAULT_LOG_LEVEL = "INFO"
+_MAX_PORT = 65535
+
+
+def _get_host() -> str:
+    """Get API host from environment.
+
+    Returns:
+        Host address to bind the API server to.
+    """
+    return os.getenv("API_HOST", _DEFAULT_HOST)
+
+
+def _get_port() -> int:
+    """Get API port from environment.
+
+    Returns:
+        Port number for the API server.
+    """
+    raw_port = os.getenv("API_PORT")
+    if raw_port is None:
+        return _DEFAULT_PORT
+
+    try:
+        port_value = int(raw_port)
+    except ValueError:
+        return _DEFAULT_PORT
+
+    if not 1 <= port_value <= _MAX_PORT:
+        return _DEFAULT_PORT
+
+    return port_value
+
+
+def _get_log_level() -> str:
+    """Get log level from environment.
+
+    Returns:
+        Log level string for uvicorn.
+    """
+    return os.getenv("API_LOG_LEVEL", _DEFAULT_LOG_LEVEL).lower()
+
+
+def main() -> None:
+    """Run the MT5 REST API with uvicorn."""
+    host = _get_host()
+    port = _get_port()
+    log_level = _get_log_level()
+
+    logging.getLogger(__name__).info("Starting MT5 REST API on %s:%s", host, port)
+    uvicorn.run(
+        "mt5api.main:app",
+        host=host,
+        port=port,
+        log_level=log_level,
+    )
+
+
+if __name__ == "__main__":
+    main()

mt5api/auth.py

@@ -0,0 +1,74 @@
+"""API key authentication for REST API endpoints."""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated
+
+from fastapi import HTTPException, Security, status
+from fastapi.security import APIKeyHeader
+
+# API key security scheme
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+# Auth mode is fixed for the lifetime of the process.
+_API_KEY: str | None = os.getenv("MT5_API_KEY") or None  # treat empty string as unset
+
+
+def get_api_key() -> str | None:
+    """Get the API key configured at startup, if any.
+
+    Returns:
+        API key string from ``MT5_API_KEY``, or ``None`` if authentication is
+        disabled.
+    """
+    return _API_KEY
+
+
+def is_auth_enabled() -> bool:
+    """Return whether API key authentication is enabled."""
+    return _API_KEY is not None
+
+
+def verify_api_key(
+    api_key_header_value: Annotated[str | None, Security(api_key_header)],
+) -> str | None:
+    """Verify API key from request header.
+
+    Args:
+        api_key_header_value: API key from X-API-Key header.
+
+    Returns:
+        Verified API key when authentication is enabled, otherwise ``None``.
+
+    Raises:
+        HTTPException: 401 if API key is missing or invalid.
+    """
+    expected_key = get_api_key()
+    if expected_key is None:
+        return None
+
+    if not api_key_header_value:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail={
+                "type": "/errors/unauthorized",
+                "title": "Authentication Required",
+                "status": 401,
+                "detail": "Missing API key. Provide X-API-Key header.",
+                "instance": None,
+            },
+        )
+
+    if api_key_header_value != expected_key:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail={
+                "type": "/errors/unauthorized",
+                "title": "Authentication Failed",
+                "status": 401,
+                "detail": "Invalid API key.",
+                "instance": None,
+            },
+        )
+
+    return api_key_header_value

mt5api/dependencies.py

@@ -0,0 +1,132 @@
+"""FastAPI dependency injection for MT5 client and format negotiation."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Annotated, Any, TypeVar
+
+from fastapi import Header, Query, Request
+from pdmt5.dataframe import Mt5Config, Mt5DataClient
+
+from .models import ResponseFormat
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# Type variable for return types
+T = TypeVar("T")
+
+# Global singleton instance
+_mt5_client: Mt5DataClient | None = None
+
+
+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 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/formatters.py

@@ -0,0 +1,159 @@
+"""Response formatters for JSON and Apache Parquet formats."""
+
+from __future__ import annotations
+
+import io
+from typing import TYPE_CHECKING, Any, 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, StreamingResponse
+
+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
+
+    @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.
+
+    Args:
+        dataframe: DataFrame to format.
+        orient: JSON orientation (records, index, columns, etc.).
+
+    Returns:
+        DataResponse model with JSON data.
+    """
+    # Convert DataFrame to dict/list based on orientation
+    if orient == "records":
+        data_value: list[dict[str, Any]] | dict[str, Any] = dataframe.to_dict(
+            orient=orient  # type: ignore[arg-type]
+        )
+    else:
+        data_value = 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.
+
+    Args:
+        data: Dictionary to format.
+
+    Returns:
+        DataResponse model with JSON data.
+    """
+    return DataResponse(
+        data=data,
+        count=1,
+        format=ResponseFormat.JSON,
+    )
+
+
+def format_dataframe_to_parquet(dataframe: pd.DataFrame) -> Response:
+    """Format DataFrame as Apache Parquet response.
+
+    Args:
+        dataframe: DataFrame to format.
+
+    Returns:
+        StreamingResponse with Parquet binary data.
+    """
+    # Convert DataFrame to Arrow Table
+    table = pa.Table.from_pandas(dataframe, preserve_index=False)
+
+    # Write to in-memory buffer
+    buffer = io.BytesIO()
+    pq.write_table(
+        table,
+        buffer,
+        compression="snappy",
+        use_dictionary=True,
+        write_statistics=True,
+    )
+    buffer.seek(0)
+
+    return StreamingResponse(
+        content=iter([buffer.getvalue()]),
+        media_type="application/parquet",
+        headers={
+            "Content-Disposition": "attachment; filename=data.parquet",
+        },
+    )
+
+
+def format_dict_to_parquet(data: dict[str, Any]) -> Response:
+    """Format dictionary as Apache Parquet response.
+
+    Args:
+        data: Dictionary to format (will be converted to single-row DataFrame).
+
+    Returns:
+        StreamingResponse with Parquet binary data.
+    """
+    # Convert dict to single-row DataFrame
+    dataframe = pd.DataFrame([data])
+    return format_dataframe_to_parquet(dataframe)
+
+
+def format_response(
+    data: object,
+    response_format: ResponseFormat,
+) -> DataResponse | Response:
+    """Format data based on requested response format.
+
+    Unified formatter that handles both DataFrame and dict data types,
+    selecting the appropriate output format (JSON or Parquet).
+
+    Args:
+        data: Data to format. Must be a pandas DataFrame or dict with string
+            keys.
+        response_format: Requested response format (JSON or Parquet).
+
+    Returns:
+        DataResponse for JSON format, StreamingResponse for Parquet format.
+
+    Raises:
+        TypeError: If the data type is neither DataFrame nor dict.
+        ValueError: If the response format is not supported.
+    """
+    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):
+        if response_format == ResponseFormat.PARQUET:
+            return format_dict_to_parquet(data)
+        return format_dict_to_json(data)
+
+    raise TypeError(_INVALID_DATA_MESSAGE)

mt5api/main.py

@@ -0,0 +1,183 @@
+"""FastAPI application instance and lifecycle management."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any
+
+from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
+from starlette.middleware.cors import CORSMiddleware
+
+from .auth import is_auth_enabled
+from .dependencies import shutdown_mt5_client
+from .middleware import add_middleware
+from .routers import account, health, history, market, symbols
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+
+
+class _JsonFormatter(logging.Formatter):
+    """JSON formatter for structured logs."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "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 = os.getenv("API_LOG_LEVEL", "INFO").upper()
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(_JsonFormatter())
+
+    root_logger = logging.getLogger()
+    root_logger.handlers.clear()
+    root_logger.setLevel(log_level)
+    root_logger.addHandler(handler)
+
+
+def _get_cors_origins() -> list[str]:
+    """Get CORS origins from environment.
+
+    Returns:
+        List of allowed origins.
+    """
+    raw_origins = os.getenv("API_CORS_ORIGINS", "*")
+    if raw_origins.strip() == "*":
+        return ["*"]
+
+    return [origin.strip() for origin in raw_origins.split(",") if origin.strip()]
+
+
+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")
+    if isinstance(components, dict):
+        security_schemes = components.get("securitySchemes")
+        if isinstance(security_schemes, dict):
+            security_schemes.pop("APIKeyHeader", None)
+            if not security_schemes:
+                components.pop("securitySchemes", None)
+
+    for methods in openapi_schema.get("paths", {}).values():
+        if not isinstance(methods, dict):
+            continue
+        for operation in methods.values():
+            if isinstance(operation, dict):
+                operation.pop("security", None)
+
+
+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.
+    """
+    if app.openapi_schema:
+        return app.openapi_schema
+
+    openapi_schema = get_openapi(
+        title=app.title,
+        version=app.version,
+        description=app.description,
+        routes=app.routes,
+    )
+    if not is_auth_enabled():
+        _strip_auth_from_openapi(openapi_schema)
+
+    app.openapi_schema = openapi_schema
+    return openapi_schema
+
+
+def _custom_openapi() -> dict[str, Any]:
+    """Build OpenAPI schema for the current application instance.
+
+    Returns:
+        OpenAPI schema for the application.
+    """
+    return _build_openapi_schema(app)
+
+
+_configure_logging()
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:  # noqa: ARG001
+    """Manage application lifespan (startup and shutdown).
+
+    Args:
+        app: FastAPI application instance (unused but required by FastAPI).
+
+    Yields:
+        None
+    """
+    # Startup
+    logger.info("Starting MT5 REST API...")
+
+    # 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...")
+    shutdown_mt5_client()
+    logger.info("MT5 connection closed")
+
+
+# Create FastAPI application
+app = FastAPI(
+    title="MT5 REST API",
+    description=(
+        "REST API for MetaTrader 5 data access. "
+        "Provides read-only access to market data, "
+        "account information, and trading history via HTTP endpoints."
+    ),
+    version="1.0.0",
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc",
+    openapi_url="/openapi.json",
+)
+app.openapi = _custom_openapi
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_get_cors_origins(),
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Add middleware
+add_middleware(app)
+
+# Include routers
+app.include_router(health.router)
+app.include_router(symbols.router)
+app.include_router(market.router)
+app.include_router(account.router)
+app.include_router(history.router)
+
+logger.info("MT5 REST API initialized")