alphafeed 0.1.0.dev0__tar.gz

alphafeed-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: alphafeed
+Version: 0.1.0.dev0
+Summary: AlphaFeed Python SDK
+Author: AlphaFeed
+License: MIT
+Project-URL: Documentation, https://docs.alphafeed.org
+Keywords: finance,stock,market-data,quant,kline,alphafeed,a-share,us-stock,hk-stock,real-time-quotes
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: tqdm>=4.60.0
+
+# AlphaFeed Python SDK
+
+AlphaFeed Python SDK 是 AlphaFeed 金融市场数据 API 的 Python 客户端，支持 A 股、ETF、美股、港股。
+
+> **完整文档**：<https://docs.alphafeed.org>
+
+---
+
+## 安装
+
+```bash
+pip install alphafeed
+```
+
+SDK 支持 Python 3.9+，推荐 3.10 或更高版本。内置 pandas 和 tqdm 支持。
+
+---
+
+## 初始化
+
+```python
+from alphafeed import AlphaFeed
+
+af = AlphaFeed(api_key="your-api-key")
+```
+
+也支持环境变量：
+
+```bash
+export ALPHAFEED_API_KEY="your-api-key"
+```
+
+```python
+from alphafeed import AlphaFeed
+af = AlphaFeed()  # 自动读取 ALPHAFEED_API_KEY
+```
+
+---
+
+## 标的代码格式
+
+| 示例 | 说明 |
+|------|------|
+| `600000.SH` | 上交所 |
+| `000001.SZ` | 深交所 |
+| `AAPL.US` | 美股 |
+| `00700.HK` | 港股 |
+
+---
+
+## 基础用法
+
+### K 线获取
+
+```python
+from alphafeed import AlphaFeed
+
+af = AlphaFeed(api_key="your-api-key")
+
+# 日 K 线，返回 DataFrame
+df = af.klines.get("600000.SH", period="1d", count=100, to_dataframe=True)
+print(df.tail())
+
+# 分钟 K 线
+df = af.klines.get("600000.SH", period="5m", count=100, to_dataframe=True)
+
+# 前复权（默认）
+df = af.klines.get("600519.SH", adjust="forward", to_dataframe=True)
+```
+
+**批量获取**：多只标的一次拉取：
+
+```python
+symbols = ["600000.SH", "000001.SZ", "600519.SH"]
+dfs = af.klines.batch(symbols, period="1d", count=100, to_dataframe=True, show_progress=True)
+print(dfs["600000.SH"].tail())
+```
+
+### 日内分时
+
+```python
+# 当日分钟线
+df = af.klines.intraday("600000.SH", to_dataframe=True)
+print(df.tail())
+
+# 批量日内分时
+dfs = af.klines.intraday_batch(["600000.SH", "000001.SZ"], to_dataframe=True)
+```
+
+### 实时行情
+
+**按标的代码查询**
+
+```python
+quotes = af.quotes.get(symbols=["600000.SH", "000001.SZ", "00700.HK"], to_dataframe=True)
+print(quotes)
+```
+
+**按标的池查询**
+
+```python
+# 全部 A 股行情
+quotes_a = af.quotes.get(universes=["CN_Stock"], to_dataframe=True)
+print(quotes_a)
+
+# 全部 ETF 行情
+quotes_etf = af.quotes.get(universes=["CN_ETF"], to_dataframe=True)
+print(quotes_etf)
+```
+
+支持的标的池：`CN_Stock`（A股）、`US_Stock`（美股）、`HK_Stock`（港股）、`CN_ETF`（ETF）
+
+### 五档盘口
+
+```python
+depth = af.depth.get("600000.SH")
+print("买盘:", depth["bids"][:5])
+print("卖盘:", depth["asks"][:5])
+```
+
+### 标的信息
+
+```python
+instruments = af.instruments.batch(symbols=["600000.SH", "000001.SZ", "00700.HK"])
+for inst in instruments:
+    print(f"{inst['symbol']}: {inst['name']}")
+```
+
+### 除权因子
+
+```python
+factors = af.klines.ex_factors(symbols=["600000.SH", "600519.SH"], to_dataframe=True)
+print(factors.tail())
+```
+
+---
+
+## 更多文档
+
+- [Python SDK 快速开始](https://docs.alphafeed.org/zh-Hans/sdk/python-quickstart)
+- [使用示例](https://docs.alphafeed.org/zh-Hans/sdk/python-examples)
+- [HTTP API 说明](https://docs.alphafeed.org/zh-Hans/api-reference/introduction)
+
+---
+
+## License
+
+MIT

alphafeed-0.1.0.dev0/README.md

@@ -0,0 +1,148 @@
+# AlphaFeed Python SDK
+
+AlphaFeed Python SDK 是 AlphaFeed 金融市场数据 API 的 Python 客户端，支持 A 股、ETF、美股、港股。
+
+> **完整文档**：<https://docs.alphafeed.org>
+
+---
+
+## 安装
+
+```bash
+pip install alphafeed
+```
+
+SDK 支持 Python 3.9+，推荐 3.10 或更高版本。内置 pandas 和 tqdm 支持。
+
+---
+
+## 初始化
+
+```python
+from alphafeed import AlphaFeed
+
+af = AlphaFeed(api_key="your-api-key")
+```
+
+也支持环境变量：
+
+```bash
+export ALPHAFEED_API_KEY="your-api-key"
+```
+
+```python
+from alphafeed import AlphaFeed
+af = AlphaFeed()  # 自动读取 ALPHAFEED_API_KEY
+```
+
+---
+
+## 标的代码格式
+
+| 示例 | 说明 |
+|------|------|
+| `600000.SH` | 上交所 |
+| `000001.SZ` | 深交所 |
+| `AAPL.US` | 美股 |
+| `00700.HK` | 港股 |
+
+---
+
+## 基础用法
+
+### K 线获取
+
+```python
+from alphafeed import AlphaFeed
+
+af = AlphaFeed(api_key="your-api-key")
+
+# 日 K 线，返回 DataFrame
+df = af.klines.get("600000.SH", period="1d", count=100, to_dataframe=True)
+print(df.tail())
+
+# 分钟 K 线
+df = af.klines.get("600000.SH", period="5m", count=100, to_dataframe=True)
+
+# 前复权（默认）
+df = af.klines.get("600519.SH", adjust="forward", to_dataframe=True)
+```
+
+**批量获取**：多只标的一次拉取：
+
+```python
+symbols = ["600000.SH", "000001.SZ", "600519.SH"]
+dfs = af.klines.batch(symbols, period="1d", count=100, to_dataframe=True, show_progress=True)
+print(dfs["600000.SH"].tail())
+```
+
+### 日内分时
+
+```python
+# 当日分钟线
+df = af.klines.intraday("600000.SH", to_dataframe=True)
+print(df.tail())
+
+# 批量日内分时
+dfs = af.klines.intraday_batch(["600000.SH", "000001.SZ"], to_dataframe=True)
+```
+
+### 实时行情
+
+**按标的代码查询**
+
+```python
+quotes = af.quotes.get(symbols=["600000.SH", "000001.SZ", "00700.HK"], to_dataframe=True)
+print(quotes)
+```
+
+**按标的池查询**
+
+```python
+# 全部 A 股行情
+quotes_a = af.quotes.get(universes=["CN_Stock"], to_dataframe=True)
+print(quotes_a)
+
+# 全部 ETF 行情
+quotes_etf = af.quotes.get(universes=["CN_ETF"], to_dataframe=True)
+print(quotes_etf)
+```
+
+支持的标的池：`CN_Stock`（A股）、`US_Stock`（美股）、`HK_Stock`（港股）、`CN_ETF`（ETF）
+
+### 五档盘口
+
+```python
+depth = af.depth.get("600000.SH")
+print("买盘:", depth["bids"][:5])
+print("卖盘:", depth["asks"][:5])
+```
+
+### 标的信息
+
+```python
+instruments = af.instruments.batch(symbols=["600000.SH", "000001.SZ", "00700.HK"])
+for inst in instruments:
+    print(f"{inst['symbol']}: {inst['name']}")
+```
+
+### 除权因子
+
+```python
+factors = af.klines.ex_factors(symbols=["600000.SH", "600519.SH"], to_dataframe=True)
+print(factors.tail())
+```
+
+---
+
+## 更多文档
+
+- [Python SDK 快速开始](https://docs.alphafeed.org/zh-Hans/sdk/python-quickstart)
+- [使用示例](https://docs.alphafeed.org/zh-Hans/sdk/python-examples)
+- [HTTP API 说明](https://docs.alphafeed.org/zh-Hans/api-reference/introduction)
+
+---
+
+## License
+
+MIT

alphafeed-0.1.0.dev0/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-0.1.0.dev0/alphafeed/__version__.py

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

alphafeed-0.1.0.dev0/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,
+        )