alphafeed 0.1.0.dev0__py3-none-any.whl

alphafeed/resources/quotes.py

@@ -0,0 +1,257 @@
+"""Real-time quote resources for AlphaFeed API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Literal, Union, overload
+
+import pandas as pd
+
+from .._types import NOT_GIVEN, NotGiven
+from ..utils import (
+    instrument_timestamp_to_trade_date,
+    instrument_timestamp_to_trade_time,
+)
+from ._base import SyncResource
+
+if TYPE_CHECKING:
+    from ..models import Quote
+
+
+def _quotes_to_dataframe(data: List["Quote"]) -> "pd.DataFrame":
+    """Convert quote data to a pandas DataFrame.
+
+    Parameters
+    ----------
+    data : list of Quote
+        List of quote dictionaries.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with symbol as index. Includes trade_date, trade_time columns
+        and flattened ext fields with "ext." prefix (e.g., ext.limit_up, ext.change_pct).
+    """
+    if not data:
+        return pd.DataFrame()
+
+    rows = []
+    for q in data:
+        row = {k: v for k, v in q.items() if k not in ("ext", "session")}
+
+        row["trade_date"] = instrument_timestamp_to_trade_date(
+            q["symbol"], q["timestamp"], unit="ms"
+        )
+        row["trade_time"] = instrument_timestamp_to_trade_time(
+            q["symbol"], q["timestamp"], unit="ms"
+        )
+
+        ext = q.get("ext")
+        if ext:
+            for key, value in ext.items():
+                if value is not None and not isinstance(value, dict):
+                    row[f"ext.{key}"] = value
+
+        rows.append(row)
+
+    df = pd.DataFrame(rows)
+    return df
+
+
+class Quotes(SyncResource):
+    """Synchronous interface for real-time quote endpoints.
+
+    Supports querying quotes by symbol codes or universe IDs.
+
+    Examples
+    --------
+    >>> client = AlphaFeed(api_key="your-key")
+    >>>
+    >>> # Get quotes by symbols
+    >>> quotes = client.quotes.get(symbols=["600000.SH", "AAPL.US"])
+    >>>
+    >>> # Get quotes by universe
+    >>> quotes = client.quotes.get(universes=["CN_Stock"])
+    """
+
+    @overload
+    def get(
+        self,
+        *,
+        symbols: Union[List[str], str, None] = None,
+        universes: Union[List[str], str, None] = None,
+        to_dataframe: Literal[False] = False,
+    ) -> List["Quote"]: ...
+
+    @overload
+    def get(
+        self,
+        *,
+        symbols: Union[List[str], str, None] = None,
+        universes: Union[List[str], str, None] = None,
+        to_dataframe: Literal[True],
+    ) -> "pd.DataFrame": ...
+
+    def get(
+        self,
+        *,
+        symbols: Union[List[str], str, None] = None,
+        universes: Union[List[str], str, None] = None,
+        to_dataframe: bool = False,
+    ) -> Union[List["Quote"], "pd.DataFrame"]:
+        """Get real-time quotes for symbols or universes.
+
+        Must provide either `symbols` or `universes`, but not both.
+
+        Parameters
+        ----------
+        symbols : str or list of str, optional
+            Symbol code(s) to query. Can be a single symbol, comma-separated
+            string, or list of symbols.
+        universes : str or list of str, optional
+            Universe ID(s) to query. Can be a single ID, comma-separated
+            string, or list of IDs.
+        to_dataframe : bool, optional
+            If True, return a pandas DataFrame indexed by symbol.
+            If False (default), return a list of Quote dicts.
+
+        Returns
+        -------
+        list of Quote or pd.DataFrame
+            Quote data for the requested symbols.
+
+            Each Quote contains:
+            - symbol: Symbol code
+            - name: Symbol name
+            - region: Region code
+            - 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
+
+        Raises
+        ------
+        ValueError
+            If neither or both of `symbols` and `universes` are provided.
+
+        Examples
+        --------
+        >>> # Query by symbols
+        >>> quotes = client.quotes.get(symbols=["600000.SH", "AAPL.US"])
+        >>> for q in quotes:
+        ...     print(f"{q['symbol']}: {q['last_price']}")
+
+        >>> # Query by universe, as DataFrame
+        >>> df = client.quotes.get(universes="CN_Stock", to_dataframe=True)
+        >>> print(df[["last_price", "volume"]].head())
+
+        >>> # Find top gainers
+        >>> df["change_pct"] = (df["last_price"] - df["prev_close"]) / df["prev_close"] * 100
+        >>> top_gainers = df.nlargest(10, "change_pct")
+        """
+        if (symbols is None) == (universes is None):
+            raise ValueError(
+                "Must provide either 'symbols' or 'universes', but not both"
+            )
+
+        if symbols is not None:
+            if isinstance(symbols, str):
+                symbols_list = [s.strip() for s in symbols.split(",")]
+            else:
+                symbols_list = symbols
+
+            if len(symbols_list) <= 20:
+                response = self._client.get(
+                    "/v1/quotes", params={"symbols": ",".join(symbols_list)}
+                )
+            else:
+                response = self._client.post(
+                    "/v1/quotes", json={"symbols": symbols_list}
+                )
+        else:
+            if isinstance(universes, str):
+                universes_list = [u.strip() for u in universes.split(",")]
+            else:
+                universes_list = universes
+
+            if len(universes_list) <= 5:
+                response = self._client.get(
+                    "/v1/quotes", params={"universes": ",".join(universes_list)}
+                )
+            else:
+                response = self._client.post(
+                    "/v1/quotes", json={"universes": universes_list}
+                )
+
+        data = response["data"]
+
+        if to_dataframe:
+            return _quotes_to_dataframe(data)
+        return data
+
+    def get_by_symbols(
+        self,
+        symbols: List[str],
+        *,
+        to_dataframe: bool = False,
+    ) -> Union[List["Quote"], "pd.DataFrame"]:
+        """Get real-time quotes for a list of symbols.
+
+        This is a convenience method that always uses POST for batch queries.
+
+        Parameters
+        ----------
+        symbols : list of str
+            List of symbol codes.
+        to_dataframe : bool, optional
+            If True, return a pandas DataFrame.
+
+        Returns
+        -------
+        list of Quote or pd.DataFrame
+            Quote data for the requested symbols.
+
+        Examples
+        --------
+        >>> quotes = client.quotes.get_by_symbols(["600000.SH", "000001.SZ", "AAPL.US"])
+        """
+        response = self._client.post("/v1/quotes", json={"symbols": symbols})
+        data = response["data"]
+
+        if to_dataframe:
+            return _quotes_to_dataframe(data)
+        return data
+
+    def get_by_universes(
+        self,
+        universes: List[str],
+        *,
+        to_dataframe: bool = False,
+    ) -> Union[List["Quote"], "pd.DataFrame"]:
+        """Get real-time quotes for all symbols in the specified universes.
+
+        Parameters
+        ----------
+        universes : list of str
+            List of universe IDs.
+        to_dataframe : bool, optional
+            If True, return a pandas DataFrame.
+
+        Returns
+        -------
+        list of Quote or pd.DataFrame
+            Quote data for all symbols in the universes.
+
+        Examples
+        --------
+        >>> # Get all A-share quotes
+        >>> quotes = client.quotes.get_by_universes(["CN_Stock"], to_dataframe=True)
+        """
+        response = self._client.post("/v1/quotes", json={"universes": universes})
+        data = response["data"]
+
+        if to_dataframe:
+            return _quotes_to_dataframe(data)
+        return data

alphafeed/utils.py

@@ -0,0 +1,53 @@
+import datetime
+from zoneinfo import ZoneInfo
+
+CN_TZ = ZoneInfo("Asia/Shanghai")
+US_TZ = ZoneInfo("America/New_York")
+HK_TZ = ZoneInfo("Asia/Hong_Kong")
+
+symbol_suffix_region_map = {
+    "SH": "CN",
+    "SZ": "CN",
+    "BJ": "CN",
+    "US": "US",
+    "HK": "HK",
+}
+
+region_timezone_map = {
+    "CN": CN_TZ,
+    "US": US_TZ,
+    "HK": HK_TZ,
+}
+
+
+def get_instrument_region(symbol: str):
+    return symbol_suffix_region_map.get(
+        symbol.rsplit(".", 1)[-1],
+    )
+
+
+def get_region_timezone(region: str):
+    return region_timezone_map.get(region)
+
+
+def instrument_timestamp_to_datetime(symbol: str, timestamp: int, unit="ms"):
+    tz = get_region_timezone(get_instrument_region(symbol))
+    if tz is None:
+        return None
+
+    dt = (
+        datetime.datetime.fromtimestamp(timestamp / 1000, tz)
+        if unit == "ms"
+        else datetime.datetime.fromtimestamp(timestamp, tz)
+    )
+    return dt
+
+
+def instrument_timestamp_to_trade_date(symbol: str, timestamp: int, unit="ms"):
+    dt = instrument_timestamp_to_datetime(symbol, timestamp, unit)
+    return dt.strftime("%Y-%m-%d")
+
+
+def instrument_timestamp_to_trade_time(symbol: str, timestamp: int, unit="ms"):
+    dt = instrument_timestamp_to_datetime(symbol, timestamp, unit)
+    return dt.strftime("%Y-%m-%d %H:%M:%S")

alphafeed-0.1.0.dev0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+alphafeed/__init__.py,sha256=rvVsIJV68pNsTSFB4IqrYD2WsZvUWZhb1lYN5nfoRxo,1071
+alphafeed/__version__.py,sha256=WHizC8UzElmTH3641zjnMTLUHmP2rliWLTalgHU6vMA,75
+alphafeed/_base_client.py,sha256=3R66eIZdyfeo-VWCNBhKh0dwoa2vNtDOdr57Lr5TOQw,9230
+alphafeed/_batch.py,sha256=f2s8FVomnpoGpes1TqHBCE7Uj0R0Xbgrun9n_cq5tOg,2630
+alphafeed/_cache.py,sha256=7NqTfFvtseEF6WfZEHuWLzEkkxSkUK--pbGRCfxSoXo,4383
+alphafeed/_exceptions.py,sha256=C-hTGXkoUe5lhsbPN54naZU_GmLgN5WargeHT394HiA,3031
+alphafeed/_types.py,sha256=Qgpp7UgF-R49ANuqetEhDszU-TXSS5ZMT4-jl5pPBeo,1191
+alphafeed/client.py,sha256=eQFHNfx6jg5qYWP1oPu5R8P0zyGca6M6rfmxP6fe8O8,4198
+alphafeed/models.py,sha256=EItKQNjdObo9YZ3EG1CusDcaTij2rDiYq4mBYs3jgzY,2014
+alphafeed/utils.py,sha256=dOJoWw4QoAg3ufcch3JtRfFmzTBwhrFo0tI2WCUGVFM,1284
+alphafeed/resources/__init__.py,sha256=GNt5jhqbFKlJYechYhjvbYksX4BEcDB-l4CuALXZglA,234
+alphafeed/resources/_base.py,sha256=Ni3EM30Y-5DhABTfGaaeX2a-xmqwHll9FAqI10TdwIE,371
+alphafeed/resources/depth.py,sha256=_ATcQvOzxWSfK_lLr0ABs5QxC5d_WPe-sIQmZG1Vq34,1232
+alphafeed/resources/instruments.py,sha256=Eiljv8GPznLkqGyQfVNm-8jzrTVjJd7PyoMpExw3JCQ,3094
+alphafeed/resources/klines.py,sha256=iNsYtyKohh6g3ml7TtCLZkuqtDQ1nKTDffJs0rY7lro,24927
+alphafeed/resources/quotes.py,sha256=nsAhff0naw37HWnZVOeK6a71pc9ZZkYnIyYm_jWPDeI,7816
+alphafeed-0.1.0.dev0.dist-info/METADATA,sha256=-h6PBH5Lf2Zj3bfKLFdk5IAkD-vU4ntrf1BXNcv3sb4,4038
+alphafeed-0.1.0.dev0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+alphafeed-0.1.0.dev0.dist-info/top_level.txt,sha256=WkGzCvhzsoEoKS1iZmBwDLMM4P6M7eCU9zylBLi1iPc,10
+alphafeed-0.1.0.dev0.dist-info/RECORD,,

alphafeed-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

alphafeed-0.1.0.dev0.dist-info/top_level.txt

@@ -0,0 +1 @@
+alphafeed