bt-api-base 0.15.1__py3-none-any.whl

bt_api_base/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from bt_api_base._version import __version__
+
+__all__ = [
+    "__version__",
+]

bt_api_base/_compat.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from datetime import timezone
+from enum import Enum
+
+try:
+    from typing import Never as _Never
+    from typing import ParamSpec as _ParamSpec
+    from typing import Self as _Self
+except ImportError:
+    from typing_extensions import Never as _Never
+    from typing_extensions import ParamSpec as _ParamSpec
+    from typing_extensions import Self as _Self
+
+try:
+    from enum import StrEnum as _StrEnum
+except ImportError:
+
+    class _StrEnum(str, Enum):
+        """Backport for Python < 3.11."""
+
+
+Never = _Never
+ParamSpec = _ParamSpec
+Self = _Self
+StrEnum = _StrEnum
+UTC = timezone.utc
+
+__all__ = ["Never", "ParamSpec", "Self", "StrEnum", "UTC"]

bt_api_base/_plugin_shims.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import warnings
+from importlib import import_module
+from typing import Any
+
+
+def reexport_plugin_module(
+    legacy_module: str,
+    plugin_module: str,
+    namespace: dict[str, Any],
+) -> tuple[list[str], Any]:
+    """Load a plugin module and expose its public symbols via a legacy path."""
+
+    warnings.warn(
+        (
+            f"{legacy_module} is deprecated. "
+            f"Install the corresponding plugin package and import from {plugin_module} instead."
+        ),
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    module = import_module(plugin_module)
+    exports = list(
+        getattr(module, "__all__", [name for name in dir(module) if not name.startswith("_")])
+    )
+    namespace.update({name: getattr(module, name) for name in exports if hasattr(module, name)})
+    return exports, module

bt_api_base/_version.py

@@ -0,0 +1,5 @@
+"""Package version metadata."""
+
+from __future__ import annotations
+
+__version__ = "0.15.0"

bt_api_base/auth_config.py

@@ -0,0 +1,171 @@
+"""认证配置 — 统一管理不同交易所的认证方式。
+
+加密货币交易所使用 API Key，CTP 使用 Broker/User/Password，IB 使用 TWS 连接参数.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlparse
+
+__all__ = [
+    "AuthConfig",
+    "CryptoAuthConfig",
+    "CtpAuthConfig",
+    "IbAuthConfig",
+    "IbWebAuthConfig",
+]
+
+
+def _require_non_empty_str(value: str, field_name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{field_name} must be a non-empty string")
+    return value.strip()
+
+
+def _validate_port(port: int, field_name: str = "port") -> int:
+    if not isinstance(port, int) or not (1 <= port <= 65535):
+        raise ValueError(f"{field_name} must be in range 1-65535")
+    return port
+
+
+def _validate_url(value: str, field_name: str) -> str:
+    parsed = urlparse(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ValueError(f"{field_name} must be a valid http/https URL")
+    return value
+
+
+def _validate_tcp_front(value: str, field_name: str) -> str:
+    parsed = urlparse(value)
+    if parsed.scheme != "tcp" or not parsed.hostname or parsed.port is None:
+        raise ValueError(f"{field_name} must be a valid tcp://host:port address")
+    return value
+
+
+class AuthConfig:
+    """认证配置基类."""
+
+    def __init__(self, exchange: str, asset_type: str = "SWAP", **kwargs: Any) -> None:
+        self.exchange = _require_non_empty_str(exchange, "exchange")
+        self.asset_type = _require_non_empty_str(asset_type, "asset_type")
+
+    def get_exchange_name(self) -> str:
+        return f"{self.exchange}___{self.asset_type}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in self.__dict__.items() if not k.startswith("_")}
+
+
+class CryptoAuthConfig(AuthConfig):
+    """加密货币交易所认证配置（Binance, OKX 等）."""
+
+    def __init__(
+        self,
+        exchange: str,
+        asset_type: str = "SWAP",
+        public_key: str | None = None,
+        private_key: str | None = None,
+        passphrase: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(exchange, asset_type, **kwargs)
+        if public_key is not None:
+            public_key = _require_non_empty_str(public_key, "public_key")
+        if private_key is not None:
+            private_key = _require_non_empty_str(private_key, "private_key")
+        if public_key is None and private_key is not None:
+            raise ValueError("public_key is required when private_key is provided")
+        if private_key is None and public_key is not None:
+            raise ValueError("private_key is required when public_key is provided")
+        self.public_key = public_key
+        self.private_key = private_key
+        self.passphrase = (
+            _require_non_empty_str(passphrase, "passphrase") if passphrase is not None else None
+        )
+
+
+class CtpAuthConfig(AuthConfig):
+    """CTP 认证配置."""
+
+    def __init__(
+        self,
+        exchange: str = "CTP",
+        asset_type: str = "FUTURE",
+        broker_id: str = "",
+        user_id: str = "",
+        password: str = "",
+        auth_code: str = "",
+        app_id: str = "",
+        md_front: str = "",
+        td_front: str = "",
+        product_info: str = "",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(exchange, asset_type, **kwargs)
+        self.broker_id = _require_non_empty_str(broker_id, "broker_id")
+        self.user_id = _require_non_empty_str(user_id, "user_id")
+        self.password = _require_non_empty_str(password, "password")
+        self.auth_code = auth_code
+        self.app_id = app_id
+        self.md_front = _validate_tcp_front(md_front, "md_front")
+        self.td_front = _validate_tcp_front(td_front, "td_front")
+        self.product_info = product_info
+
+
+class IbAuthConfig(AuthConfig):
+    """Interactive Brokers 认证配置."""
+
+    def __init__(
+        self,
+        exchange: str = "IB",
+        asset_type: str = "STK",
+        host: str = "127.0.0.1",
+        port: int = 7497,
+        client_id: int = 1,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(exchange, asset_type, **kwargs)
+        self.host = _require_non_empty_str(host, "host")
+        self.port = _validate_port(port, "port")
+        if not isinstance(client_id, int) or client_id < 0:
+            raise ValueError("client_id must be a non-negative integer")
+        self.client_id = client_id
+
+
+class IbWebAuthConfig(AuthConfig):
+    """Interactive Brokers Web API 认证配置."""
+
+    def __init__(
+        self,
+        exchange: str = "IB_WEB",
+        asset_type: str = "STK",
+        base_url: str = "https://localhost:5000",
+        account_id: str | None = None,
+        access_token: str | None = None,
+        client_id: str | None = None,
+        private_key_path: str | None = None,
+        verify_ssl: bool = False,
+        proxies: dict[str, str] | None = None,
+        timeout: int = 10,
+        cookies: dict[str, str] | None = None,
+        cookie_source: str | None = None,
+        cookie_browser: str = "chrome",
+        cookie_path: str = "/sso",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(exchange, asset_type, **kwargs)
+        self.base_url = _validate_url(base_url, "base_url")
+        self.account_id = account_id
+        self.access_token = access_token
+        self.client_id = client_id
+        self.private_key_path = private_key_path
+        self.verify_ssl = verify_ssl
+        self.proxies = proxies
+        if not isinstance(timeout, int) or timeout <= 0:
+            raise ValueError("timeout must be a positive integer")
+        self.timeout = timeout
+        self.cookies = cookies
+        self.cookie_source = cookie_source
+        self.cookie_browser = cookie_browser
+        self.cookie_path = cookie_path

bt_api_base/balance_utils.py

@@ -0,0 +1,99 @@
+"""
+通用余额解析工具函数
+将各交易所重复的 balance_handler 逻辑抽取到此处
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bt_api_base.containers.accounts.account import AccountData
+    from bt_api_base.containers.balances.balance import BalanceData
+
+
+def _to_float(value: float | int | None) -> float:
+    """Coerce numeric balance fields while tolerating missing values."""
+    return float(value) if value is not None else 0.0
+
+
+def _currency_key(value: str | None) -> str:
+    """Normalize currency keys used in aggregated balance maps."""
+    return value or ""
+
+
+def _apply_balance_values(
+    value_result: dict[str, dict[str, float]],
+    cash_result: dict[str, dict[str, float]],
+    currency: str,
+    margin: float | int | None,
+    available_margin: float | int | None,
+    unrealized_profit: float | int | None,
+) -> None:
+    cash_result[currency] = {"cash": _to_float(available_margin)}
+    value_result[currency] = {"value": _to_float(margin) + _to_float(unrealized_profit)}
+
+
+def simple_balance_handler(
+    account_list: list[AccountData],
+) -> tuple[dict[str, dict[str, float]], dict[str, dict[str, float]]]:
+    """通用余额解析处理函数（适用于 Binance/CTP/IB 等单层账户结构）。
+
+    Args:
+        account_list: 账户数据列表，每个元素实现 get_account_type、get_available_margin 等接口。
+
+    Returns:
+        (value_result, cash_result): value_result 为 {currency: {"value": float}}，
+        cash_result 为 {currency: {"cash": float}}。
+    """
+    value_result: dict[str, dict[str, float]] = {}
+    cash_result: dict[str, dict[str, float]] = {}
+    for account in account_list:
+        account.init_data()
+        currency = _currency_key(account.get_account_type())
+        _apply_balance_values(
+            value_result,
+            cash_result,
+            currency,
+            account.get_margin(),
+            account.get_available_margin(),
+            account.get_unrealized_profit(),
+        )
+    return value_result, cash_result
+
+
+def nested_balance_handler(
+    account_list: list[AccountData],
+) -> tuple[dict[str, dict[str, float]], dict[str, dict[str, float]]]:
+    """嵌套余额解析处理函数（适用于 OKX 等多层账户结构）。
+
+    Args:
+        account_list: 账户数据列表，每个 account 内含 get_balances() 返回 balance 列表。
+
+    Returns:
+        (value_result, cash_result): 同 simple_balance_handler。
+    """
+    value_result: dict[str, dict[str, float]] = {}
+    cash_result: dict[str, dict[str, float]] = {}
+    for account in account_list:
+        account.init_data()
+        for balance in account.get_balances():
+            balance.init_data()
+            _update_nested_balance(value_result, cash_result, balance)
+    return value_result, cash_result
+
+
+def _update_nested_balance(
+    value_result: dict[str, dict[str, float]],
+    cash_result: dict[str, dict[str, float]],
+    balance: BalanceData,
+) -> None:
+    currency = _currency_key(balance.get_symbol_name())
+    _apply_balance_values(
+        value_result,
+        cash_result,
+        currency,
+        balance.get_margin(),
+        balance.get_available_margin(),
+        balance.get_unrealized_profit(),
+    )

bt_api_base/cache.py

@@ -0,0 +1,212 @@
+"""
+Caching utilities for performance optimization.
+
+Provides in-memory caching for frequently accessed data like exchange info,
+trading pairs, and market data.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict
+from collections.abc import Callable, Iterator
+from functools import wraps
+from typing import Any, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+_CACHE_MISSING = object()
+
+__all__ = [
+    "SimpleCache",
+    "ExchangeInfoCache",
+    "MarketDataCache",
+    "cached",
+    "get_exchange_info_cache",
+    "get_market_data_cache",
+]
+
+
+class SimpleCache:
+    """
+    Simple in-memory cache with TTL (Time To Live) support.
+
+    Features:
+    - Key-value storage with expiration
+    - Automatic cleanup of expired entries
+    - Thread-safe operations (basic)
+    """
+
+    def __init__(self, default_ttl: float = 300.0, max_size: int | None = 10000) -> None:
+        self._cache: OrderedDict[str, tuple[Any, float]] = OrderedDict()
+        self._default_ttl = default_ttl
+        self._max_size = max_size
+        self._lock = threading.RLock()
+        self._hits = 0
+        self._misses = 0
+
+    def _get_or_default(self, key: str, default: Any) -> Any:
+        with self._lock:
+            cached_entry = self._cache.get(key)
+            if cached_entry is None:
+                self._misses += 1
+                return default
+
+            value, expiry = cached_entry
+            if time.time() > expiry:
+                self._cache.pop(key, None)
+                self._misses += 1
+                return default
+
+            self._hits += 1
+            self._cache.move_to_end(key)
+            return value
+
+    def get(self, key: str) -> Any | None:
+        return self._get_or_default(key, None)
+
+    def set(self, key: str, value: Any, ttl: float | None = None) -> None:
+        if ttl is None:
+            ttl = self._default_ttl
+
+        expiry = time.time() + ttl
+        with self._lock:
+            if key in self._cache:
+                self._cache.pop(key)
+            self._cache[key] = (value, expiry)
+            if self._max_size is not None and self._max_size > 0:
+                while len(self._cache) > self._max_size:
+                    self._cache.popitem(last=False)
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._cache.pop(key, None)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._cache.clear()
+
+    def cleanup(self) -> int:
+        with self._lock:
+            now = time.time()
+            active_cache: OrderedDict[str, tuple[Any, float]] = OrderedDict()
+            removed = 0
+            for key, entry in self._cache.items():
+                if now > entry[1]:
+                    removed += 1
+                else:
+                    active_cache[key] = entry
+            self._cache = active_cache
+            return removed
+
+    def size(self) -> int:
+        with self._lock:
+            return len(self._cache)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.keys())
+
+    def keys(self) -> list[str]:
+        with self._lock:
+            return list(self._cache.keys())
+
+    def get_stats(self) -> dict[str, float]:
+        with self._lock:
+            total = self._hits + self._misses
+            hit_rate = self._hits / total if total else 0.0
+            return {
+                "size": float(len(self._cache)),
+                "hits": float(self._hits),
+                "misses": float(self._misses),
+                "hit_rate": hit_rate,
+            }
+
+
+class ExchangeInfoCache:
+    """Specialized cache for exchange information."""
+
+    def __init__(self, ttl: float = 3600.0) -> None:
+        self._cache = SimpleCache(default_ttl=ttl)
+
+    def get_trading_pairs(self, exchange: str) -> list[str] | None:
+        return self._cache.get(f"{exchange}:trading_pairs")
+
+    def set_trading_pairs(self, exchange: str, pairs: list[str]) -> None:
+        self._cache.set(f"{exchange}:trading_pairs", pairs)
+
+    def get_exchange_info(self, exchange: str, symbol: str) -> dict[str, Any] | None:
+        return self._cache.get(f"{exchange}:{symbol}:info")
+
+    def set_exchange_info(self, exchange: str, symbol: str, info: dict[str, Any]) -> None:
+        self._cache.set(f"{exchange}:{symbol}:info", info)
+
+    def clear_exchange(self, exchange: str) -> None:
+        keys_to_delete = [key for key in self._cache if key.startswith(f"{exchange}:")]
+        for key in keys_to_delete:
+            self._cache.delete(key)
+
+
+class MarketDataCache:
+    """Cache for market data with shorter TTL."""
+
+    def __init__(self, ttl: float = 5.0) -> None:
+        self._cache = SimpleCache(default_ttl=ttl)
+
+    def get_ticker(self, exchange: str, symbol: str) -> Any | None:
+        return self._cache.get(f"{exchange}:{symbol}:ticker")
+
+    def set_ticker(self, exchange: str, symbol: str, ticker: Any) -> None:
+        self._cache.set(f"{exchange}:{symbol}:ticker", ticker)
+
+    def get_orderbook(self, exchange: str, symbol: str) -> Any | None:
+        return self._cache.get(f"{exchange}:{symbol}:orderbook")
+
+    def set_orderbook(self, exchange: str, symbol: str, orderbook: Any) -> None:
+        self._cache.set(f"{exchange}:{symbol}:orderbook", orderbook)
+
+
+def cached(
+    ttl: float = 300.0,
+    cache_instance: SimpleCache | None = None,
+    maxsize: int | None = None,
+) -> Callable[[F], F]:
+    """Decorator for caching function results."""
+    if cache_instance is None:
+        cache_instance = SimpleCache(default_ttl=ttl, max_size=maxsize)
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            key_parts = [func.__name__]
+            key_parts.extend(str(arg) for arg in args)
+            key_parts.extend(f"{k}={v}" for k, v in sorted(kwargs.items()))
+            cache_key = ":".join(key_parts)
+
+            cached_value = cache_instance._get_or_default(cache_key, _CACHE_MISSING)
+            if cached_value is not _CACHE_MISSING:
+                return cached_value
+
+            result = func(*args, **kwargs)
+            cache_instance.set(cache_key, result, ttl)
+            return result
+
+        wrapper.cache = cache_instance  # type: ignore
+        wrapper.clear_cache = cache_instance.clear  # type: ignore
+        wrapper.cache_stats = cache_instance.get_stats  # type: ignore
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+# Global cache instances
+_exchange_info_cache = ExchangeInfoCache()
+_market_data_cache = MarketDataCache()
+
+
+def get_exchange_info_cache() -> ExchangeInfoCache:
+    return _exchange_info_cache
+
+
+def get_market_data_cache() -> MarketDataCache:
+    return _market_data_cache