xtb-api-python 0.5.2__py3-none-any.whl

xtb_api/__init__.py

@@ -0,0 +1,70 @@
+"""Unofficial Python client for XTB xStation5 trading platform."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from xtb_api.auth.auth_manager import AuthManager as XTBAuth
+from xtb_api.client import XTBClient
+from xtb_api.exceptions import (
+    AuthenticationError,
+    CASError,
+    InstrumentNotFoundError,
+    ProtocolError,
+    RateLimitError,
+    ReconnectionError,
+    TradeError,
+    XTBConnectionError,
+    XTBError,
+    XTBTimeoutError,
+)
+from xtb_api.instruments import InstrumentRegistry
+from xtb_api.types.enums import (
+    SocketStatus,
+    SubscriptionEid,
+    Xs6Side,
+    XTBEnvironment,
+)
+from xtb_api.types.instrument import InstrumentSearchResult, Quote
+from xtb_api.types.trading import (
+    AccountBalance,
+    PendingOrder,
+    Position,
+    TradeOptions,
+    TradeResult,
+)
+
+try:
+    __version__ = _pkg_version("xtb-api-python")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    # Client
+    "XTBClient",
+    "XTBAuth",
+    "InstrumentRegistry",
+    # Exceptions
+    "XTBError",
+    "XTBConnectionError",
+    "AuthenticationError",
+    "CASError",
+    "ReconnectionError",
+    "TradeError",
+    "InstrumentNotFoundError",
+    "RateLimitError",
+    "XTBTimeoutError",
+    "ProtocolError",
+    # Data models
+    "Position",
+    "PendingOrder",
+    "AccountBalance",
+    "TradeResult",
+    "TradeOptions",
+    "Quote",
+    "InstrumentSearchResult",
+    # Enums
+    "Xs6Side",
+    "SocketStatus",
+    "XTBEnvironment",
+    "SubscriptionEid",
+]

xtb_api/__main__.py

@@ -0,0 +1,154 @@
+"""CLI entry point for xtb-api-python.
+
+Usage:
+    python -m xtb_api doctor   # Verify installation state
+    xtb-api doctor             # Same, if the entry point script is on PATH
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import platform
+import sys
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+
+def _ok(label: str, detail: str = "") -> str:
+    return f"  [OK]   {label}" + (f" — {detail}" if detail else "")
+
+
+def _fail(label: str, detail: str = "") -> str:
+    return f"  [FAIL] {label}" + (f" — {detail}" if detail else "")
+
+
+def _info(label: str, detail: str = "") -> str:
+    return f"  [--]   {label}" + (f" — {detail}" if detail else "")
+
+
+def _check_python_version() -> tuple[bool, str]:
+    major, minor = sys.version_info[:2]
+    version_str = f"{major}.{minor}.{sys.version_info[2]}"
+    ok = (major, minor) >= (3, 12)
+    return ok, version_str
+
+
+def _check_package_version() -> tuple[bool, str]:
+    try:
+        return True, _pkg_version("xtb-api-python")
+    except PackageNotFoundError:
+        return False, "not installed (are you running from a non-installed checkout?)"
+
+
+def _check_playwright_package() -> tuple[bool, str]:
+    spec = importlib.util.find_spec("playwright")
+    if spec is None:
+        return False, "playwright Python package not installed"
+    try:
+        ver = _pkg_version("playwright")
+    except PackageNotFoundError:
+        ver = "unknown"
+    return True, f"playwright {ver}"
+
+
+def _check_chromium_binary() -> tuple[bool, str]:
+    """Attempt to locate the Chromium executable without launching it."""
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        return False, "playwright not importable"
+
+    try:
+        with sync_playwright() as p:
+            exe = p.chromium.executable_path
+            # executable_path is a property that returns a string path; does not
+            # guarantee the file exists. Probe it.
+            from pathlib import Path
+
+            if exe and Path(exe).exists():
+                return True, exe
+            return False, f"expected binary at {exe!r} not found"
+    except Exception as e:  # noqa: BLE001
+        return False, f"playwright check failed: {e}"
+
+
+def _check_pyotp_optional() -> tuple[bool, str]:
+    spec = importlib.util.find_spec("pyotp")
+    if spec is None:
+        return False, "pyotp not installed (install 'xtb-api-python[totp]' for auto-2FA)"
+    try:
+        ver = _pkg_version("pyotp")
+    except PackageNotFoundError:
+        ver = "unknown"
+    return True, f"pyotp {ver}"
+
+
+def run_doctor() -> int:
+    """Run environment checks and print a status report. Returns 0 on success."""
+    print(f"xtb-api-python doctor — {platform.platform()}")
+    print()
+
+    all_ok = True
+
+    # Required checks
+    ok, detail = _check_python_version()
+    print(_ok("Python >= 3.12", detail) if ok else _fail("Python >= 3.12", detail))
+    all_ok &= ok
+
+    ok, detail = _check_package_version()
+    print(_ok("xtb-api-python", detail) if ok else _fail("xtb-api-python", detail))
+    all_ok &= ok
+
+    ok, detail = _check_playwright_package()
+    print(_ok("playwright package", detail) if ok else _fail("playwright package", detail))
+    all_ok &= ok
+
+    ok, detail = _check_chromium_binary()
+    if ok:
+        print(_ok("Chromium binary", detail))
+    else:
+        print(_fail("Chromium binary", detail))
+        print()
+        print("  To install Chromium, run:")
+        print("      playwright install chromium")
+        print()
+        all_ok = False
+
+    # Optional checks
+    ok, detail = _check_pyotp_optional()
+    print(_ok("pyotp (optional 2FA)", detail) if ok else _info("pyotp (optional 2FA)", detail))
+
+    print()
+    if all_ok:
+        print("All required checks passed.")
+        return 0
+    print("Some required checks failed. See above for fix instructions.")
+    return 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="xtb-api",
+        description="xtb-api-python CLI",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser("doctor", help="Verify the library's installation state")
+
+    try:
+        args = parser.parse_args()
+    except SystemExit as e:
+        # argparse raises SystemExit on --help or parse errors. Convert to
+        # a return value so main() stays testable and honors its -> int contract.
+        code = e.code
+        if isinstance(code, int):
+            return code
+        return 2
+
+    if args.command == "doctor":
+        return run_doctor()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

xtb_api/auth/__init__.py

@@ -0,0 +1,5 @@
+"""CAS authentication module."""
+
+from xtb_api.auth.auth_manager import AuthManager as AuthManager
+from xtb_api.auth.cas_client import CASClient as CASClient
+from xtb_api.auth.cas_client import CASClientConfig as CASClientConfig

xtb_api/auth/auth_manager.py

@@ -0,0 +1,321 @@
+"""High-level authentication manager that encapsulates the full TGT auth flow.
+
+Handles cached sessions, REST CAS login, browser fallback, and automatic TOTP —
+so consumers don't need to implement the auth chain themselves.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import stat
+import time
+from concurrent.futures import ThreadPoolExecutor
+from datetime import UTC, datetime
+from pathlib import Path
+
+from xtb_api.auth.cas_client import CASClient, CASClientConfig
+from xtb_api.types.websocket import (
+    CASError,
+    CASLoginSuccess,
+    CASLoginTwoFactorRequired,
+)
+
+logger = logging.getLogger(__name__)
+
+# TGT validity: 8 hours, but refresh 5 minutes early to avoid races
+TGT_LIFETIME_SECONDS = 8 * 3600
+TGT_REFRESH_MARGIN_SECONDS = 5 * 60
+
+
+class AuthManager:
+    """Manages the full XTB CAS authentication chain.
+
+    Auth chain (tried in order):
+    1. Cached TGT from session file (if configured and still valid)
+    2. REST CAS login (fast, no browser)
+    3. Playwright browser fallback (if WAF blocks REST)
+    4. Automatic TOTP if 2FA required and totp_secret provided
+
+    Example::
+
+        auth = AuthManager(
+            email="user@example.com",
+            password="secret",
+            totp_secret="BASE32SECRET",
+            session_file="~/.xtb_session.json",
+        )
+        tgt = await auth.get_tgt()
+        st = await auth.get_service_ticket()
+    """
+
+    def __init__(
+        self,
+        email: str,
+        password: str,
+        totp_secret: str = "",
+        session_file: Path | str | None = None,
+        cas_config: CASClientConfig | None = None,
+        cookies_file: Path | str | None = None,
+    ) -> None:
+        """
+        Args:
+            email: XTB account email.
+            password: XTB account password.
+            totp_secret: Base32 TOTP secret for auto-2FA (optional).
+                         If omitted and 2FA is required, raises CASError.
+            session_file: Path to cache TGT as JSON (optional).
+                          If omitted, TGT is only cached in memory.
+            cas_config: Custom CAS client configuration (optional).
+            cookies_file: Path to persist HTTP cookies as JSON (optional).
+                          If omitted but ``session_file`` is set, defaults to
+                          ``<session_file_stem>_cookies.json`` alongside it.
+        """
+        self._email = email
+        self._password = password
+        self._totp_secret = totp_secret
+        self._session_file = Path(session_file).expanduser() if session_file else None
+
+        # Derive cookies_file from session_file when not explicitly provided
+        if cookies_file is None and self._session_file is not None:
+            cookies_file = self._session_file.parent / f"{self._session_file.stem}_cookies.json"
+
+        # Inject cookies_file into CAS config
+        if cookies_file is not None:
+            cas_config = (cas_config or CASClientConfig()).model_copy(update={"cookies_file": cookies_file})
+
+        self._cas = CASClient(cas_config)
+        self._cached_tgt: str | None = None
+        self._cached_expires_at: float = 0.0
+
+    async def get_tgt(self) -> str:
+        """Get a valid TGT, using the full auth chain as needed.
+
+        Chain: cached (memory/file) -> REST CAS -> browser fallback -> TOTP.
+
+        Returns:
+            Valid TGT string.
+
+        Raises:
+            CASError: If authentication fails at all stages.
+        """
+        # 1. Check in-memory cache
+        if self._cached_tgt and self._is_tgt_fresh(self._cached_expires_at):
+            return self._cached_tgt
+
+        # 2. Check session file
+        if self._session_file:
+            cached = self._load_session_file()
+            if cached:
+                tgt = str(cached["tgt"])
+                self._cached_tgt = tgt
+                self._cached_expires_at = float(cached["expires_at"])
+                return tgt
+
+        # 3. REST CAS login
+        result = await self._login_with_fallback()
+
+        # 4. Handle 2FA if needed
+        if isinstance(result, CASLoginTwoFactorRequired):
+            result = await self._handle_two_factor(result)
+
+        # 5. Cache and return
+        self._cache_tgt(result.tgt, result.expires_at)
+        return result.tgt
+
+    def get_tgt_sync(self) -> str:
+        """Synchronous wrapper for :meth:`get_tgt`.
+
+        Uses a dedicated thread with its own event loop to avoid conflicts
+        with any running loop in the caller's thread.
+        """
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(lambda: asyncio.run(self.get_tgt())).result()
+
+    async def get_service_ticket(self, service: str = "xapi5") -> str:
+        """Get a service ticket, obtaining a TGT first if needed.
+
+        Args:
+            service: CAS service name. Use ``'xapi5'`` for WebSocket,
+                     ``'abigail'`` for REST API.
+
+        Returns:
+            Service ticket string (``ST-...``).
+
+        Raises:
+            CASError: If TGT acquisition or service ticket request fails.
+        """
+        tgt = await self.get_tgt()
+        try:
+            st_result = await self._cas.get_service_ticket(tgt, service)
+            return st_result.service_ticket
+        except CASError as e:
+            if e.code == "CAS_TGT_EXPIRED":
+                # TGT was cached but expired server-side — clear and retry
+                self._invalidate_cache()
+                tgt = await self.get_tgt()
+                st_result = await self._cas.get_service_ticket(tgt, service)
+                return st_result.service_ticket
+            raise
+
+    def invalidate(self) -> None:
+        """Clear cached TGT from memory and session file."""
+        self._invalidate_cache()
+
+    async def aclose(self) -> None:
+        """Close underlying HTTP clients. Call on shutdown."""
+        await self._cas.aclose()
+
+    # -- Internal helpers --
+
+    async def _login_with_fallback(self) -> CASLoginSuccess | CASLoginTwoFactorRequired:
+        """Try REST CAS login, fall back to browser if WAF blocks."""
+        try:
+            return await self._cas.login(self._email, self._password)
+        except CASError as e:
+            # Invalid credentials — don't retry with browser
+            if "UNAUTHORIZED" in e.code:
+                raise
+            logger.info("REST CAS login failed (%s), trying browser fallback", e.code)
+            return await self._cas.login_with_browser(self._email, self._password)
+        except Exception as e:
+            # WAF often returns HTML instead of JSON → httpx decode error
+            logger.info("REST CAS login failed (%s), trying browser fallback", e)
+            return await self._cas.login_with_browser(self._email, self._password)
+
+    async def _handle_two_factor(self, challenge: CASLoginTwoFactorRequired) -> CASLoginSuccess:
+        """Handle 2FA challenge using TOTP auto-generation or browser OTP."""
+        code = await self._generate_totp()
+
+        # If browser session is active, prefer browser OTP (WAF blocks REST 2FA too)
+        if hasattr(self._cas, "_browser_auth") and self._cas._browser_auth:
+            logger.info("Submitting TOTP via browser OTP...")
+            result = await self._cas.submit_browser_otp(code)
+        else:
+            # Try REST 2FA submission
+            two_factor_type = "TOTP" if "TOTP" in challenge.methods else challenge.two_factor_auth_type
+            result = await self._cas.login_with_two_factor(challenge.login_ticket, code, two_factor_type)
+
+        if isinstance(result, CASLoginTwoFactorRequired):
+            raise CASError(
+                "AUTH_MANAGER_2FA_LOOP",
+                "Server requested 2FA again after submitting code",
+            )
+
+        return result
+
+    async def _generate_totp(self) -> str:
+        """Generate a TOTP code from the stored secret.
+
+        If fewer than 2 seconds remain in the current 30-second TOTP window,
+        waits for the next window before generating the code. Without this,
+        roughly 6.6% of logins fail because the code expires in transit before
+        the server validates it. Waiting (rather than returning the next
+        window's code) avoids relying on server-side window-drift tolerance.
+        """
+        if not self._totp_secret:
+            raise CASError(
+                "AUTH_MANAGER_2FA_NO_SECRET",
+                "2FA is required but no totp_secret was provided. "
+                "Pass totp_secret to AuthManager or disable 2FA on your account.",
+            )
+        try:
+            import pyotp
+        except ImportError as e:
+            raise CASError(
+                "AUTH_MANAGER_PYOTP_MISSING",
+                "2FA requires the pyotp package. Install with: pip install 'pyotp>=2.9.0'",
+            ) from e
+        totp = pyotp.TOTP(self._totp_secret)
+        remaining = totp.interval - (time.time() % totp.interval)
+        if remaining < 2:
+            # Within 2s of window boundary — wait for the next window so the
+            # generated code is guaranteed valid for its full lifetime.
+            await asyncio.sleep(remaining + 0.1)
+        return str(totp.now())
+
+    def _cache_tgt(self, tgt: str, expires_at: float) -> None:
+        """Cache TGT in memory and optionally to session file."""
+        self._cached_tgt = tgt
+        self._cached_expires_at = expires_at
+
+        if self._session_file:
+            self._save_session_file(tgt, expires_at)
+
+    def _invalidate_cache(self) -> None:
+        """Clear TGT from memory and session file."""
+        self._cached_tgt = None
+        self._cached_expires_at = 0.0
+
+        if self._session_file and self._session_file.exists():
+            self._session_file.unlink(missing_ok=True)
+
+    def _load_session_file(self) -> dict | None:
+        """Load and validate cached TGT from session file.
+
+        Returns:
+            Dict with 'tgt' and 'expires_at' if valid, None otherwise.
+        """
+        if not self._session_file or not self._session_file.exists():
+            return None
+
+        try:
+            # Fix permissions if file is readable by group/others (TGT is sensitive)
+            file_mode = self._session_file.stat().st_mode & 0o777
+            if file_mode & 0o077:
+                logger.warning(
+                    "Session file %s has permissive permissions (%o). Fixing to 0600.",
+                    self._session_file,
+                    file_mode,
+                )
+                self._session_file.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+            data = json.loads(self._session_file.read_text())
+            tgt = data.get("tgt", "")
+            expires_at_str = data.get("expires_at", "")
+
+            if not tgt or not expires_at_str:
+                return None
+
+            expires_at = datetime.fromisoformat(expires_at_str).timestamp()
+
+            if not self._is_tgt_fresh(expires_at):
+                return None
+
+            return {"tgt": tgt, "expires_at": expires_at}
+        except (json.JSONDecodeError, KeyError, ValueError, OSError):
+            return None
+
+    def _save_session_file(self, tgt: str, expires_at: float) -> None:
+        """Save TGT to session file as JSON with restricted permissions (0600)."""
+        if not self._session_file:
+            return
+
+        extracted_at = datetime.now(UTC)
+        expires_at_dt = datetime.fromtimestamp(expires_at, tz=UTC)
+
+        data = {
+            "tgt": tgt,
+            "extracted_at": extracted_at.isoformat(),
+            "expires_at": expires_at_dt.isoformat(),
+        }
+
+        self._session_file.parent.mkdir(parents=True, exist_ok=True)
+        content = json.dumps(data, indent=2)
+        # Write with owner-only permissions to protect the TGT
+        fd = os.open(
+            str(self._session_file),
+            os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+            stat.S_IRUSR | stat.S_IWUSR,  # 0600
+        )
+        try:
+            os.write(fd, content.encode())
+        finally:
+            os.close(fd)
+
+    @staticmethod
+    def _is_tgt_fresh(expires_at: float) -> bool:
+        """Check if TGT is still valid with a safety margin."""
+        return time.time() < (expires_at - TGT_REFRESH_MARGIN_SECONDS)