alphafeed 0.1.0.dev0__py3-none-any.whl

alphafeed/__init__.py

@@ -0,0 +1,53 @@
+"""AlphaFeed Python SDK - 高性能行情数据客户端。
+
+支持 A股、ETF、美股、港股的行情数据查询。
+
+Examples
+--------
+>>> from alphafeed import AlphaFeed
+>>> client = AlphaFeed(api_key="your-api-key")
+>>> df = client.klines.get("600000.SH", to_dataframe=True)
+>>> print(df.tail())
+"""
+
+from .__version__ import __version__
+from ._exceptions import (
+    AlphaFeedError,
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    InternalServerError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    TimeoutError,
+)
+from .client import AlphaFeed
+from .models import (
+    AdjustType,
+    CompactKlineData,
+    Instrument,
+    Period,
+    Quote,
+)
+
+__all__ = [
+    "__version__",
+    "AlphaFeed",
+    "AlphaFeedError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "BadRequestError",
+    "RateLimitError",
+    "InternalServerError",
+    "ConnectionError",
+    "TimeoutError",
+    "AdjustType",
+    "CompactKlineData",
+    "Instrument",
+    "Period",
+    "Quote",
+]

alphafeed/__version__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version(__package__)

alphafeed/_base_client.py

@@ -0,0 +1,305 @@
+"""Base HTTP client implementation with retry support."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from typing import Any, Optional, Union
+
+import httpx
+
+from . import __version__
+from ._exceptions import (
+    APIError,
+    ConnectionError,
+    InternalServerError,
+    RateLimitError,
+    TimeoutError,
+    raise_for_status,
+)
+from ._types import NOT_GIVEN, Headers, NotGiven, Query, Timeout
+
+__all__ = ["SyncAPIClient"]
+
+DEFAULT_BASE_URL = "https://api.alphafeed.org"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+
+def _should_retry(exception: Exception) -> bool:
+    """Determine if an exception is retryable.
+
+    Parameters
+    ----------
+    exception : Exception
+        The exception to check.
+
+    Returns
+    -------
+    bool
+        True if the request should be retried.
+    """
+    if isinstance(exception, (ConnectionError, TimeoutError)):
+        return True
+
+    if isinstance(exception, (InternalServerError, RateLimitError)):
+        return True
+
+    return False
+
+
+def _calculate_retry_delay(
+    attempt: int, base_delay: float = 1.0, max_delay: float = 30.0
+) -> float:
+    """Calculate exponential backoff delay with jitter.
+
+    Parameters
+    ----------
+    attempt : int
+        Current attempt number (0-indexed).
+    base_delay : float
+        Base delay in seconds.
+    max_delay : float
+        Maximum delay in seconds.
+
+    Returns
+    -------
+    float
+        Delay in seconds.
+    """
+    delay = base_delay * (2**attempt)
+    jitter = delay * 0.25 * (2 * random.random() - 1)
+    delay = delay + jitter
+    return min(delay, max_delay)
+
+
+class BaseClient:
+    """Base class with shared configuration for API clients."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Headers] = None,
+    ) -> None:
+        if api_key is None:
+            self.api_key = os.environ.get("ALPHAFEED_API_KEY")
+        else:
+            self.api_key = api_key
+
+        if not self.api_key:
+            effective_base_url = base_url or os.environ.get("ALPHAFEED_BASE_URL")
+            if effective_base_url is None or effective_base_url == DEFAULT_BASE_URL:
+                raise ValueError(
+                    "API key is required. Pass `api_key` or set ALPHAFEED_API_KEY environment variable."
+                )
+
+        self.base_url = (
+            base_url or os.environ.get("ALPHAFEED_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._default_headers = dict(default_headers) if default_headers else {}
+
+    def _build_headers(self, extra_headers: Optional[Headers] = None) -> dict[str, str]:
+        """Build request headers with authentication."""
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"alphafeed-python/{__version__}",
+            **self._default_headers,
+        }
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        if extra_headers:
+            headers.update(extra_headers)
+        return headers
+
+    def _build_url(self, path: str) -> str:
+        """Build full URL from path."""
+        return f"{self.base_url}{path}"
+
+
+class SyncAPIClient(BaseClient):
+    """Synchronous HTTP client for AlphaFeed API with automatic retry.
+
+    Parameters
+    ----------
+    api_key : str, optional
+        API key for authentication. If not provided, reads from ALPHAFEED_API_KEY
+        environment variable.
+    base_url : str, optional
+        Base URL for the API. Defaults to https://api.alphafeed.org.
+    timeout : float, optional
+        Request timeout in seconds. Defaults to 30.0.
+    max_retries : int, optional
+        Maximum number of retry attempts for failed requests. Defaults to 3.
+        Retries occur on connection errors, timeouts, server errors (5xx),
+        and rate limits (429).
+    default_headers : dict, optional
+        Default headers to include in all requests.
+
+    Examples
+    --------
+    >>> client = SyncAPIClient(api_key="your-api-key")
+    >>> response = client.get("/v1/klines", params={"symbol": "600000.SH"})
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Headers] = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries, default_headers)
+        self._client = httpx.Client(timeout=timeout)
+
+    def __enter__(self) -> "SyncAPIClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Query] = None,
+        json: Optional[dict[str, Any]] = None,
+        extra_headers: Optional[Headers] = None,
+        timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make an HTTP request with automatic retry on failures.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method (GET, POST, etc.).
+        path : str
+            API endpoint path.
+        params : dict, optional
+            Query parameters.
+        json : dict, optional
+            JSON request body.
+        extra_headers : dict, optional
+            Additional headers for this request.
+        timeout : float, optional
+            Override timeout for this request.
+        max_retries : int, optional
+            Override max retries for this request.
+
+        Returns
+        -------
+        Any
+            Parsed JSON response.
+
+        Raises
+        ------
+        APIError
+            If the API returns an error response after all retries.
+        ConnectionError
+            If there's a network connection issue after all retries.
+        TimeoutError
+            If the request times out after all retries.
+        """
+        url = self._build_url(path)
+        headers = self._build_headers(extra_headers)
+        request_timeout = timeout if not isinstance(timeout, NotGiven) else self.timeout
+        retries = (
+            max_retries if not isinstance(max_retries, NotGiven) else self.max_retries
+        )
+
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        last_exception: Optional[Exception] = None
+
+        for attempt in range(retries + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json,
+                    headers=headers,
+                    timeout=request_timeout,
+                )
+
+                try:
+                    response_body = response.json()
+                except Exception:
+                    response_body = {"message": response.text, "code": "PARSE_ERROR"}
+
+                raise_for_status(response.status_code, response_body)
+
+                return response_body
+
+            except httpx.ConnectError as e:
+                last_exception = ConnectionError(f"Failed to connect to {url}: {e}")
+            except httpx.TimeoutException as e:
+                last_exception = TimeoutError(f"Request to {url} timed out")
+            except APIError as e:
+                last_exception = e
+                if not _should_retry(e):
+                    raise
+
+            if attempt < retries and _should_retry(last_exception):
+                delay = _calculate_retry_delay(attempt)
+                time.sleep(delay)
+            else:
+                break
+
+        if last_exception:
+            raise last_exception
+        raise RuntimeError("Unexpected state: no exception but request failed")
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: Optional[Query] = None,
+        extra_headers: Optional[Headers] = None,
+        timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make a GET request with automatic retry."""
+        return self._request(
+            "GET",
+            path,
+            params=params,
+            extra_headers=extra_headers,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[Query] = None,
+        extra_headers: Optional[Headers] = None,
+        timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make a POST request with automatic retry."""
+        return self._request(
+            "POST",
+            path,
+            json=json,
+            params=params,
+            extra_headers=extra_headers,
+            timeout=timeout,
+            max_retries=max_retries,
+        )

alphafeed/_batch.py

@@ -0,0 +1,87 @@
+"""Generic batched GET utilities for splitting large symbol lists across requests.
+
+Handles URL length limits by automatically chunking the symbol list and
+merging ``response["data"]`` dicts from each chunk.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional
+
+from tqdm.auto import tqdm
+
+if TYPE_CHECKING:
+    from ._base_client import SyncAPIClient
+
+DEFAULT_BATCH_SIZE = 100
+DEFAULT_MAX_WORKERS = 5
+
+
+def _chunk_list(lst: List[str], chunk_size: int) -> List[List[str]]:
+    return [lst[i : i + chunk_size] for i in range(0, len(lst), chunk_size)]
+
+
+def _get_progress_bar(total: int, desc: str, show: bool):
+    if show:
+        return tqdm(total=total, desc=desc, leave=False)
+    return None
+
+
+def batched_get_sync(
+    client: "SyncAPIClient",
+    endpoint: str,
+    symbols: List[str],
+    params: Dict[str, Any],
+    *,
+    symbols_param: str = "symbols",
+    batch_size: int = DEFAULT_BATCH_SIZE,
+    max_workers: int = DEFAULT_MAX_WORKERS,
+    show_progress: bool = False,
+    progress_desc: str = "Fetching data",
+    merge: Optional[Callable[[Dict[str, Any], Dict[str, Any]], None]] = None,
+) -> Dict[str, Any]:
+    """Fetch *endpoint* in chunks, merging ``response["data"]`` dicts.
+
+    Parameters
+    ----------
+    merge : callable, optional
+        ``merge(accumulated, chunk_data)`` – custom merge strategy.
+        Defaults to ``accumulated.update(chunk_data)``.
+    """
+    if not symbols:
+        return {}
+
+    if isinstance(symbols, str):
+        symbols = symbols.split(",")
+
+    chunks = _chunk_list(symbols, batch_size)
+    _merge = merge or _default_merge
+
+    if len(chunks) == 1:
+        chunk_params = {**params, symbols_param: ",".join(chunks[0])}
+        return client.get(endpoint, params=chunk_params)["data"]
+
+    pbar = _get_progress_bar(len(chunks), progress_desc, show_progress)
+    all_data: Dict[str, Any] = {}
+
+    def _fetch(chunk: List[str]) -> Dict[str, Any]:
+        chunk_params = {**params, symbols_param: ",".join(chunk)}
+        return client.get(endpoint, params=chunk_params)["data"]
+
+    try:
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as pool:
+            futures = {pool.submit(_fetch, c): c for c in chunks}
+            for future in concurrent.futures.as_completed(futures):
+                _merge(all_data, future.result())
+                if pbar:
+                    pbar.update(1)
+    finally:
+        if pbar:
+            pbar.close()
+
+    return all_data
+
+
+def _default_merge(acc: Dict[str, Any], chunk: Dict[str, Any]) -> None:
+    acc.update(chunk)

alphafeed/_cache.py

@@ -0,0 +1,130 @@
+"""Local instrument name cache for AlphaFeed.
+
+Caches symbol -> name mappings to avoid frequent API calls.
+Cache directory is configurable via ALPHAFEED_CACHE_DIR environment variable.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from ._base_client import SyncAPIClient
+
+logger = logging.getLogger("alphafeed.cache")
+
+DEFAULT_CACHE_DIR = os.path.join(Path.home(), ".alphafeed", "cache")
+CACHE_FILENAME = "instruments.json"
+CACHE_TTL_SECONDS = 24 * 60 * 60  # 24 hours
+MAX_BATCH_SIZE = 500
+
+
+def _get_cache_dir() -> str:
+    return os.environ.get("ALPHAFEED_CACHE_DIR", DEFAULT_CACHE_DIR)
+
+
+class InstrumentNameCache:
+    """Thread-safe local cache for instrument names.
+
+    Backed by an in-memory dict and a JSON file on disk.
+    Resolves missing names from the instruments API on demand.
+    """
+
+    def __init__(self, cache_dir: Optional[str] = None) -> None:
+        self._cache_dir = cache_dir or _get_cache_dir()
+        self._names: Dict[str, str] = {}
+        self._updated_at: float = 0.0
+        self._lock = threading.Lock()
+        self._load_from_disk()
+
+    @property
+    def _cache_path(self) -> str:
+        return os.path.join(self._cache_dir, CACHE_FILENAME)
+
+    def get_name(self, symbol: str) -> Optional[str]:
+        with self._lock:
+            return self._names.get(symbol)
+
+    def get_names(self, symbols: List[str]) -> Dict[str, str]:
+        with self._lock:
+            return {s: self._names[s] for s in symbols if s in self._names}
+
+    def missing(self, symbols: List[str]) -> List[str]:
+        with self._lock:
+            return [s for s in symbols if s not in self._names]
+
+    def update(self, names: Dict[str, str]) -> None:
+        if not names:
+            return
+        with self._lock:
+            self._names.update(names)
+            self._updated_at = time.time()
+        self._save_to_disk()
+
+    def resolve_sync(
+        self, symbols: List[str], client: "SyncAPIClient"
+    ) -> Dict[str, str]:
+        """Resolve names for symbols, fetching missing ones via sync client."""
+        missing = self.missing(symbols)
+        if missing:
+            self._fetch_sync(missing, client)
+        return self.get_names(symbols)
+
+    def _fetch_sync(self, symbols: List[str], client: "SyncAPIClient") -> None:
+        try:
+            for i in range(0, len(symbols), MAX_BATCH_SIZE):
+                chunk = symbols[i : i + MAX_BATCH_SIZE]
+                response = client.post("/v1/instruments", json={"symbols": chunk})
+                names = {
+                    inst["symbol"]: inst["name"]
+                    for inst in response.get("data", [])
+                    if inst.get("name")
+                }
+                self.update(names)
+        except Exception as e:
+            logger.debug("Failed to fetch instrument names: %s", e)
+
+    def _load_from_disk(self) -> None:
+        path = self._cache_path
+        if not os.path.exists(path):
+            return
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+
+            meta = data.get("_meta", {})
+            saved_at = meta.get("updated_at", 0)
+
+            if time.time() - saved_at > CACHE_TTL_SECONDS:
+                logger.debug("Cache expired, ignoring disk cache")
+                return
+
+            names = data.get("data", {})
+            if isinstance(names, dict):
+                with self._lock:
+                    self._names.update(names)
+                    self._updated_at = saved_at
+                logger.debug("Loaded %d instrument names from cache", len(names))
+        except Exception as e:
+            logger.debug("Failed to load cache from %s: %s", path, e)
+
+    def _save_to_disk(self) -> None:
+        path = self._cache_path
+        try:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with self._lock:
+                payload = {
+                    "_meta": {"updated_at": self._updated_at, "version": 1},
+                    "data": dict(self._names),
+                }
+            with open(path, "w", encoding="utf-8") as f:
+                json.dump(payload, f, ensure_ascii=False)
+        except Exception as e:
+            logger.debug("Failed to save cache to %s: %s", path, e)