alphafeed 0.1.0.dev0__tar.gz → 0.1.0.dev2__tar.gz

alphafeed-0.1.0.dev2/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: alphafeed
+Version: 0.1.0.dev2
+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
+```
+
+---
+
+## 标的代码格式
+
+| 示例 | 说明 |
+|------|------|
+| `600519.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("600519.SH", period="1d", count=5, to_dataframe=True)
+print(df[["trade_date", "open", "high", "low", "close", "volume"]])
+#    trade_date     open     high      low    close  volume
+# 0  2026-06-02  1306.00  1326.36  1301.00  1307.22   36362
+# 1  2026-06-03  1304.00  1304.00  1276.00  1281.91   52477
+# 2  2026-06-04  1278.99  1288.99  1266.69  1268.00   33506
+# 3  2026-06-05  1278.00  1283.00  1267.74  1272.86   31304
+# 4  2026-06-08  1272.00  1278.00  1260.00  1262.98   30828
+
+# 比例前复权（默认）/ 比例后复权 / 差值前复权 / 差值后复权 / 不复权
+df = af.klines.get("600519.SH", adjust="forward", to_dataframe=True)
+df = af.klines.get("600519.SH", adjust="backward", to_dataframe=True)
+df = af.klines.get("600519.SH", adjust="forward_additive", to_dataframe=True)
+df = af.klines.get("600519.SH", adjust="backward_additive", to_dataframe=True)
+df = af.klines.get("600519.SH", adjust="none", to_dataframe=True)
+```
+
+**批量获取**：多只标的一次拉取：
+
+```python
+symbols = ["600519.SH", "000001.SZ", "601318.SH"]
+dfs = af.klines.batch(symbols, period="1d", count=5, to_dataframe=True, show_progress=True)
+# dfs 是 dict: {"600519.SH": DataFrame, "000001.SZ": DataFrame, ...}
+print(dfs["600519.SH"][["trade_date", "close"]])
+```
+
+### 日内分时
+
+```python
+# 当日 1 分钟线
+df = af.klines.intraday("600519.SH", to_dataframe=True)
+print(df[["trade_time", "close", "volume"]].tail())
+#               trade_time    close  volume
+# 236  2026-06-08 14:56:00  1263.00     191
+# 237  2026-06-08 14:57:00  1262.99     126
+# 238  2026-06-08 14:58:00  1263.00       6
+# 239  2026-06-08 14:59:00  1263.00       0
+# 240  2026-06-08 15:00:00  1262.98     254
+
+# 5 分钟线
+df = af.klines.intraday("600519.SH", period="5m", to_dataframe=True)
+
+# 批量日内分时
+dfs = af.klines.intraday_batch(["600519.SH", "000001.SZ"], to_dataframe=True)
+```
+
+### 实时行情
+
+**按标的代码查询**
+
+```python
+df = af.quotes.get(symbols=["600519.SH", "000001.SZ"], to_dataframe=True)
+print(df[["symbol", "last_price", "volume", "ext.name", "ext.change_pct"]])
+#       symbol  last_price   volume ext.name  ext.change_pct
+# 0  000001.SZ       11.03  1090926     平安银行        0.004554
+# 1  600519.SH     1262.98    30828     贵州茅台       -0.007762
+```
+
+**按标的池查询（全量行情）**
+
+```python
+# 全部 A 股实时行情
+df = af.quotes.get(universes="CN_Stock", to_dataframe=True)
+print(f"共 {len(df)} 只标的")
+
+# 全部 ETF 行情
+df = af.quotes.get(universes="CN_ETF", to_dataframe=True)
+```
+
+支持的标的池：`CN_Stock`（A股）、`US_Stock`（美股）、`HK_Stock`（港股）、`CN_ETF`（ETF）
+
+### 五档盘口
+
+```python
+depth = af.depth.get("600519.SH")
+print(f"标的: {depth['symbol']}, 地区: {depth['region']}")
+print(f"买盘价: {depth['bid_prices']}")   # [1262.98, 1262.65, ...]
+print(f"买盘量: {depth['bid_volumes']}")  # [2, 1, ...]
+print(f"卖盘价: {depth['ask_prices']}")   # [1262.99, 1263.0, ...]
+print(f"卖盘量: {depth['ask_volumes']}")  # [7, 44, ...]
+```
+
+### 标的信息
+
+```python
+# 单个标的
+inst = af.instruments.get("600519.SH")
+print(f"{inst['symbol']}: {inst['name']} ({inst['exchange']}, {inst['type']})")
+# 600519.SH: 贵州茅台 (SH, stock)
+print(f"上市日期: {inst['ext']['listing_date']}")
+# 上市日期: 2001-08-27
+
+# 批量查询
+insts = af.instruments.batch(["600519.SH", "000001.SZ", "00700.HK"])
+for i in insts:
+    print(f"{i['symbol']}: {i['name']} ({i['region']})")
+# 600519.SH: 贵州茅台 (CN)
+# 000001.SZ: 平安银行 (CN)
+# 00700.HK: 腾讯控股 (HK)
+```
+
+### 复权因子
+
+```python
+df = af.klines.ex_factors(["600519.SH", "000001.SZ"], to_dataframe=True)
+print(df[["symbol", "trade_date", "ex_factor"]].tail())
+#        symbol  trade_date  ex_factor
+# 52  000001.SZ  2023-06-14   1.024369
+# 53  000001.SZ  2024-06-14   1.071428
+# 54  000001.SZ  2024-10-10   1.021872
+# 55  000001.SZ  2025-06-12   1.031331
+# 56  000001.SZ  2025-10-15   1.021505
+```
+
+---
+
+## 更多文档
+
+- [Python SDK 快速开始](https://docs.alphafeed.org/zh-Hans/sdk/python-quickstart)
+- [使用示例](https://docs.alphafeed.org/zh-Hans/sdk/python-examples)
+- [REST API 说明](https://docs.alphafeed.org/zh-Hans/api-reference/introduction)
+
+---
+
+## License
+
+MIT

alphafeed-0.1.0.dev2/README.md

@@ -0,0 +1,187 @@
+# 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
+```
+
+---
+
+## 标的代码格式
+
+| 示例 | 说明 |
+|------|------|
+| `600519.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("600519.SH", period="1d", count=5, to_dataframe=True)
+print(df[["trade_date", "open", "high", "low", "close", "volume"]])
+#    trade_date     open     high      low    close  volume
+# 0  2026-06-02  1306.00  1326.36  1301.00  1307.22   36362
+# 1  2026-06-03  1304.00  1304.00  1276.00  1281.91   52477
+# 2  2026-06-04  1278.99  1288.99  1266.69  1268.00   33506
+# 3  2026-06-05  1278.00  1283.00  1267.74  1272.86   31304
+# 4  2026-06-08  1272.00  1278.00  1260.00  1262.98   30828
+
+# 比例前复权（默认）/ 比例后复权 / 差值前复权 / 差值后复权 / 不复权
+df = af.klines.get("600519.SH", adjust="forward", to_dataframe=True)
+df = af.klines.get("600519.SH", adjust="backward", to_dataframe=True)
+df = af.klines.get("600519.SH", adjust="forward_additive", to_dataframe=True)
+df = af.klines.get("600519.SH", adjust="backward_additive", to_dataframe=True)
+df = af.klines.get("600519.SH", adjust="none", to_dataframe=True)
+```
+
+**批量获取**：多只标的一次拉取：
+
+```python
+symbols = ["600519.SH", "000001.SZ", "601318.SH"]
+dfs = af.klines.batch(symbols, period="1d", count=5, to_dataframe=True, show_progress=True)
+# dfs 是 dict: {"600519.SH": DataFrame, "000001.SZ": DataFrame, ...}
+print(dfs["600519.SH"][["trade_date", "close"]])
+```
+
+### 日内分时
+
+```python
+# 当日 1 分钟线
+df = af.klines.intraday("600519.SH", to_dataframe=True)
+print(df[["trade_time", "close", "volume"]].tail())
+#               trade_time    close  volume
+# 236  2026-06-08 14:56:00  1263.00     191
+# 237  2026-06-08 14:57:00  1262.99     126
+# 238  2026-06-08 14:58:00  1263.00       6
+# 239  2026-06-08 14:59:00  1263.00       0
+# 240  2026-06-08 15:00:00  1262.98     254
+
+# 5 分钟线
+df = af.klines.intraday("600519.SH", period="5m", to_dataframe=True)
+
+# 批量日内分时
+dfs = af.klines.intraday_batch(["600519.SH", "000001.SZ"], to_dataframe=True)
+```
+
+### 实时行情
+
+**按标的代码查询**
+
+```python
+df = af.quotes.get(symbols=["600519.SH", "000001.SZ"], to_dataframe=True)
+print(df[["symbol", "last_price", "volume", "ext.name", "ext.change_pct"]])
+#       symbol  last_price   volume ext.name  ext.change_pct
+# 0  000001.SZ       11.03  1090926     平安银行        0.004554
+# 1  600519.SH     1262.98    30828     贵州茅台       -0.007762
+```
+
+**按标的池查询（全量行情）**
+
+```python
+# 全部 A 股实时行情
+df = af.quotes.get(universes="CN_Stock", to_dataframe=True)
+print(f"共 {len(df)} 只标的")
+
+# 全部 ETF 行情
+df = af.quotes.get(universes="CN_ETF", to_dataframe=True)
+```
+
+支持的标的池：`CN_Stock`（A股）、`US_Stock`（美股）、`HK_Stock`（港股）、`CN_ETF`（ETF）
+
+### 五档盘口
+
+```python
+depth = af.depth.get("600519.SH")
+print(f"标的: {depth['symbol']}, 地区: {depth['region']}")
+print(f"买盘价: {depth['bid_prices']}")   # [1262.98, 1262.65, ...]
+print(f"买盘量: {depth['bid_volumes']}")  # [2, 1, ...]
+print(f"卖盘价: {depth['ask_prices']}")   # [1262.99, 1263.0, ...]
+print(f"卖盘量: {depth['ask_volumes']}")  # [7, 44, ...]
+```
+
+### 标的信息
+
+```python
+# 单个标的
+inst = af.instruments.get("600519.SH")
+print(f"{inst['symbol']}: {inst['name']} ({inst['exchange']}, {inst['type']})")
+# 600519.SH: 贵州茅台 (SH, stock)
+print(f"上市日期: {inst['ext']['listing_date']}")
+# 上市日期: 2001-08-27
+
+# 批量查询
+insts = af.instruments.batch(["600519.SH", "000001.SZ", "00700.HK"])
+for i in insts:
+    print(f"{i['symbol']}: {i['name']} ({i['region']})")
+# 600519.SH: 贵州茅台 (CN)
+# 000001.SZ: 平安银行 (CN)
+# 00700.HK: 腾讯控股 (HK)
+```
+
+### 复权因子
+
+```python
+df = af.klines.ex_factors(["600519.SH", "000001.SZ"], to_dataframe=True)
+print(df[["symbol", "trade_date", "ex_factor"]].tail())
+#        symbol  trade_date  ex_factor
+# 52  000001.SZ  2023-06-14   1.024369
+# 53  000001.SZ  2024-06-14   1.071428
+# 54  000001.SZ  2024-10-10   1.021872
+# 55  000001.SZ  2025-06-12   1.031331
+# 56  000001.SZ  2025-10-15   1.021505
+```
+
+---
+
+## 更多文档
+
+- [Python SDK 快速开始](https://docs.alphafeed.org/zh-Hans/sdk/python-quickstart)
+- [使用示例](https://docs.alphafeed.org/zh-Hans/sdk/python-examples)
+- [REST API 说明](https://docs.alphafeed.org/zh-Hans/api-reference/introduction)
+
+---
+
+## License
+
+MIT

{alphafeed-0.1.0.dev0 → alphafeed-0.1.0.dev2}/alphafeed/_cache.py

@@ -80,7 +80,10 @@ class InstrumentNameCache:
         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})
+                symbols_str = ",".join(chunk)
+                response = client.get(
+                    "/v1/instruments", params={"symbols": symbols_str}
+                )
                 names = {
                     inst["symbol"]: inst["name"]
                     for inst in response.get("data", [])

{alphafeed-0.1.0.dev0 → alphafeed-0.1.0.dev2}/alphafeed/models.py

@@ -1,12 +1,16 @@
+# generated by datamodel-codegen:
+#   filename:  openapi.json
+#   timestamp: 2026-06-08T08:16:35+00:00
+
 from __future__ import annotations
 
 from typing import Any, Dict, List, Literal, TypedDict
 
-from typing_extensions import NotRequired
-
-Period = Literal["1m", "5m", "15m", "30m", "60m", "1d", "1w", "1M", "1Q", "1Y"]
+from typing_extensions import NotRequired, TypeAlias
 
-AdjustType = Literal["none", "forward", "backward", "forward_additive", "backward_additive"]
+AdjustType: TypeAlias = Literal[
+    "none", "forward", "backward", "forward_additive", "backward_additive"
+]
 
 
 class CompactKlineData(TypedDict):
@@ -34,25 +38,18 @@ class ExFactorsResponse(TypedDict):
     data: Dict[str, List[ExFactorEntry]]
 
 
-
-class Instrument(TypedDict):
-    currency: NotRequired[str]
-    exchange: str
-    instrument_type: Literal[
-        "stock", "etf", "index", "bond", "fund", "futures", "options", "other"
-    ]
-    list_date: NotRequired[str]
-    name: str
-    region: Literal["CN", "US", "HK"]
-    symbol: str
+class FinancialsResponse(TypedDict):
+    data: Dict[str, List[Dict[str, Any]]]
 
 
-class InstrumentsBatchRequest(TypedDict):
-    symbols: List[str]
-
-
-class InstrumentsResponse(TypedDict):
-    data: List[Instrument]
+class InstrumentExt(TypedDict):
+    float_shares: NotRequired[float]
+    limit_down: NotRequired[float]
+    limit_up: NotRequired[float]
+    listing_date: NotRequired[str]
+    tick_size: NotRequired[float]
+    total_shares: NotRequired[float]
+    type: NotRequired[str]
 
 
 class KlineBatchResponse(TypedDict):
@@ -73,9 +70,49 @@ class MarketDepth(TypedDict):
     timestamp: int
 
 
+Period: TypeAlias = Literal[
+    "1m", "5m", "15m", "30m", "60m", "1d", "1w", "1M", "1Q", "1Y"
+]
+
+
+class QuoteExt(TypedDict):
+    amplitude: NotRequired[float]
+    change_amount: NotRequired[float]
+    change_pct: NotRequired[float]
+    name: NotRequired[str]
+    turnover_rate: NotRequired[float]
+    type: NotRequired[str]
+
+
+class RateLimitResponse(TypedDict):
+    code: int
+    message: str
+    retry_after_ms: int
+
+
+class DepthResponse(TypedDict):
+    data: MarketDepth
+
+
+class Instrument(TypedDict):
+    code: str
+    exchange: str
+    ext: NotRequired[InstrumentExt]
+    name: str
+    region: Literal["CN", "US", "HK"]
+    symbol: str
+    type: Literal[
+        "stock", "etf", "index", "bond", "fund", "futures", "options", "other"
+    ]
+
+
+class InstrumentsResponse(TypedDict):
+    data: List[Instrument]
+
+
 class Quote(TypedDict):
     amount: float
-    ext: NotRequired[Dict[str, Any]]
+    ext: NotRequired[QuoteExt]
     high: float
     last_price: float
     low: float
@@ -89,13 +126,3 @@ class Quote(TypedDict):
 
 class QuotesResponse(TypedDict):
     data: List[Quote]
-
-
-class RateLimitResponse(TypedDict):
-    code: int
-    message: str
-    retry_after_ms: int
-
-
-class DepthResponse(TypedDict):
-    data: MarketDepth

{alphafeed-0.1.0.dev0 → alphafeed-0.1.0.dev2}/alphafeed/resources/instruments.py

@@ -16,7 +16,7 @@ class Instruments(SyncResource):
     Examples
     --------
     >>> client = AlphaFeed(api_key="your-key")
-    >>> inst = client.instruments.get("600000.SH")
+    >>> inst = client.instruments.get("600519.SH")
     >>> print(f"{inst['symbol']}: {inst['name']}")
     """
 
@@ -43,44 +43,46 @@ class Instruments(SyncResource):
             If a list is provided, returns a list of Instrument dicts.
 
             Each Instrument contains:
-            - symbol: Full symbol code (e.g., "600000.SH")
-            - code: Exchange-specific code (e.g., "600000")
-            - exchange: Exchange code (e.g., "SH")
-            - region: Region code (e.g., "CN")
-            - name: Instrument name
-            - instrument_type: Type (stock, etf, index, etc.)
-            - ext: Market-specific extension data
+            - symbol: Full symbol code (e.g., "600519.SH")
+            - code: Exchange-specific code (e.g., "600519")
+            - exchange: Exchange code (e.g., "SH", "SZ", "HK", "US")
+            - region: Region code ("CN", "US", "HK")
+            - name: Instrument name (e.g., "贵州茅台")
+            - type: Type (stock, etf, index, etc.)
+            - ext: Market-specific extension data (listing_date, total_shares, etc.)
 
         Examples
         --------
         >>> # Single instrument
-        >>> inst = client.instruments.get("600000.SH")
-        >>> print(inst['name'])
+        >>> inst = client.instruments.get("600519.SH")
+        >>> print(f"{inst['name']} ({inst['exchange']})")
+        贵州茅台 (SH)
 
         >>> # Multiple instruments
-        >>> insts = client.instruments.get(["600000.SH", "AAPL.US"])
+        >>> insts = client.instruments.get(["600519.SH", "000001.SZ"])
         >>> for i in insts:
         ...     print(f"{i['symbol']}: {i['name']}")
+        600519.SH: 贵州茅台
+        000001.SZ: 平安银行
         """
         if isinstance(symbol, str):
             response = self._client.get("/v1/instruments", params={"symbols": symbol})
             data = response["data"]
             return data[0] if data else {}
         else:
-            response = self._client.post(
-                "/v1/instruments/batch", json={"symbols": symbol}
+            symbols_str = ",".join(symbol)
+            response = self._client.get(
+                "/v1/instruments", params={"symbols": symbols_str}
             )
             return response["data"]
 
     def batch(self, symbols: List[str]) -> List["Instrument"]:
         """Get metadata for multiple instruments.
 
-        This method uses POST to handle large batches without URL length limits.
-
         Parameters
         ----------
         symbols : list of str
-            List of symbol codes (up to 1000).
+            List of symbol codes.
 
         Returns
         -------
@@ -89,11 +91,13 @@ class Instruments(SyncResource):
 
         Examples
         --------
-        >>> insts = client.instruments.batch(["600000.SH", "000001.SZ", "AAPL.US"])
+        >>> insts = client.instruments.batch(["600519.SH", "000001.SZ", "00700.HK"])
         >>> for i in insts:
-        ...     print(f"{i['symbol']}: {i['name']}")
+        ...     print(f"{i['symbol']}: {i['name']} ({i['region']})")
+        600519.SH: 贵州茅台 (CN)
+        000001.SZ: 平安银行 (CN)
+        00700.HK: 腾讯控股 (HK)
         """
-        response = self._client.post(
-            "/v1/instruments/batch", json={"symbols": symbols}
-        )
+        symbols_str = ",".join(symbols)
+        response = self._client.get("/v1/instruments", params={"symbols": symbols_str})
         return response["data"]

{alphafeed-0.1.0.dev0 → alphafeed-0.1.0.dev2}/alphafeed/resources/quotes.py

@@ -120,16 +120,15 @@ class Quotes(SyncResource):
             Quote data for the requested symbols.
 
             Each Quote contains:
-            - symbol: Symbol code
-            - name: Symbol name
-            - region: Region code
+            - symbol: Symbol code (e.g., "600519.SH")
+            - region: Region code ("CN", "US", "HK")
             - last_price: Latest price
             - prev_close: Previous close
             - open, high, low: OHLC prices
             - volume: Trading volume
             - amount: Trading amount
             - timestamp: Quote timestamp (milliseconds)
-            - ext: Market-specific extension data
+            - ext: Extension data (name, change_pct, change_amount, amplitude, turnover_rate)
 
         Raises
         ------