alphafeed 0.1.0.dev0__py3-none-any.whl

alphafeed/_exceptions.py

@@ -0,0 +1,140 @@
+"""Custom exceptions for the AlphaFeed SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class AlphaFeedError(Exception):
+    """Base exception for all AlphaFeed SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class APIError(AlphaFeedError):
+    """Error returned by the AlphaFeed API.
+
+    Attributes
+    ----------
+    message : str
+        Human-readable error message.
+    code : str
+        Error code returned by the API (e.g., "INVALID_PERIOD", "SYMBOL_NOT_FOUND").
+    status_code : int
+        HTTP status code.
+    details : Any, optional
+        Additional error details for debugging.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        status_code: int,
+        details: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.details = details
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"code={self.code!r}, "
+            f"status_code={self.status_code})"
+        )
+
+
+class AuthenticationError(APIError):
+    """Authentication failed (401)."""
+
+    pass
+
+
+class PermissionError(APIError):
+    """Permission denied (403)."""
+
+    pass
+
+
+class NotFoundError(APIError):
+    """Resource not found (404)."""
+
+    pass
+
+
+class BadRequestError(APIError):
+    """Invalid request parameters (400)."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Rate limit exceeded (429)."""
+
+    pass
+
+
+class InternalServerError(APIError):
+    """Server error (5xx)."""
+
+    pass
+
+
+class ConnectionError(AlphaFeedError):
+    """Network connection error."""
+
+    pass
+
+
+class TimeoutError(AlphaFeedError):
+    """Request timeout."""
+
+    pass
+
+
+def raise_for_status(status_code: int, response_body: dict[str, Any]) -> None:
+    """Raise an appropriate exception based on status code and response body.
+
+    Parameters
+    ----------
+    status_code : int
+        HTTP status code.
+    response_body : dict
+        Parsed JSON response body.
+
+    Raises
+    ------
+    APIError
+        Appropriate subclass based on the status code.
+    """
+    if status_code < 400:
+        return
+
+    message = response_body.get("message", "Unknown error")
+    code = response_body.get("code", "UNKNOWN")
+    details = response_body.get("details")
+
+    error_cls: type[APIError]
+
+    if status_code == 400:
+        error_cls = BadRequestError
+    elif status_code == 401:
+        error_cls = AuthenticationError
+    elif status_code == 403:
+        error_cls = PermissionError
+    elif status_code == 404:
+        error_cls = NotFoundError
+    elif status_code == 429:
+        error_cls = RateLimitError
+    elif status_code >= 500:
+        error_cls = InternalServerError
+    else:
+        error_cls = APIError
+
+    raise error_cls(message, code=code, status_code=status_code, details=details)

alphafeed/_types.py

@@ -0,0 +1,55 @@
+"""Custom types and sentinel values for the AlphaFeed SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, TypeVar, Union
+
+import pandas as pd
+
+__all__ = [
+    "NOT_GIVEN",
+    "NotGiven",
+    "Headers",
+    "Query",
+    "Timeout",
+]
+
+
+class _NotGiven:
+    """Sentinel class for distinguishing omitted arguments from None.
+
+    This allows us to differentiate between:
+    - `param=None` (explicitly passing None)
+    - `param` not provided (using the default)
+    """
+
+    __slots__ = ()
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN = _NotGiven()
+
+NotGiven = _NotGiven
+
+Headers = Mapping[str, str]
+Query = Mapping[str, Union[str, int, bool, None]]
+Timeout = Union[float, None]
+
+T = TypeVar("T")
+
+DataFrameType = TypeVar("DataFrameType", bound="pd.DataFrame")
+
+
+def is_given(value: Any) -> bool:
+    """Check if a value was explicitly provided (not NOT_GIVEN)."""
+    return not isinstance(value, _NotGiven)
+
+
+def strip_not_given(params: dict[str, Any]) -> dict[str, Any]:
+    """Remove NOT_GIVEN values from a dictionary."""
+    return {k: v for k, v in params.items() if is_given(v)}

alphafeed/client.py

@@ -0,0 +1,140 @@
+"""Main client class for AlphaFeed API."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ._base_client import DEFAULT_MAX_RETRIES, SyncAPIClient
+from ._cache import InstrumentNameCache
+from ._types import Headers, Timeout
+from .resources import (
+    Depth,
+    Instruments,
+    Klines,
+    Quotes,
+)
+
+__all__ = ["AlphaFeed"]
+
+
+class AlphaFeed:
+    """Synchronous client for AlphaFeed market data API.
+
+    Provides access to market data including K-lines, quotes, instruments,
+    and market depth.
+
+    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.
+        Can also be set via ALPHAFEED_BASE_URL environment variable.
+    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, and server errors (5xx).
+    default_headers : dict, optional
+        Default headers to include in all requests.
+
+    Attributes
+    ----------
+    klines : Klines
+        K-line (OHLCV) data endpoints, including adjustment factors.
+        Supports DataFrame conversion and forward/backward adjustment.
+    quotes : Quotes
+        Real-time quote endpoints.
+    depth : Depth
+        Market depth (5-level order book) endpoint.
+    instruments : Instruments
+        Instrument metadata endpoints.
+
+    Examples
+    --------
+    Basic usage:
+
+    >>> from alphafeed import AlphaFeed
+    >>>
+    >>> client = AlphaFeed(api_key="your-api-key")
+    >>>
+    >>> # Get forward-adjusted K-line data (default)
+    >>> df = client.klines.get("600519.SH", to_dataframe=True)
+    >>>
+    >>> # Get unadjusted K-line data
+    >>> df_raw = client.klines.get("600519.SH", adjust="none", to_dataframe=True)
+    >>>
+    >>> # Get adjustment factors
+    >>> factors = client.klines.ex_factors(["600519.SH"], to_dataframe=True)
+
+    Using context manager:
+
+    >>> with AlphaFeed(api_key="your-api-key") as client:
+    ...     df = client.klines.get("AAPL.US", to_dataframe=True)
+    ...     print(df.tail())
+
+    Using environment variable:
+
+    >>> import os
+    >>> os.environ["ALPHAFEED_API_KEY"] = "your-api-key"
+    >>> client = AlphaFeed()  # Uses ALPHAFEED_API_KEY
+    """
+
+    klines: Klines
+    quotes: Quotes
+    depth: Depth
+    instruments: Instruments
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: Timeout = 30.0,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Headers] = None,
+        cache_dir: Optional[str] = None,
+    ) -> None:
+        self._client = SyncAPIClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+        )
+        self._instrument_cache = InstrumentNameCache(cache_dir=cache_dir)
+
+        self.klines = Klines(self._client, instrument_cache=self._instrument_cache)
+        self.quotes = Quotes(self._client)
+        self.depth = Depth(self._client)
+        self.instruments = Instruments(self._client)
+
+    def __enter__(self) -> "AlphaFeed":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client.
+
+        This releases any network resources held by the client.
+        Called automatically when using the client as a context manager.
+        """
+        self._client.close()
+
+    @property
+    def instrument_cache(self) -> InstrumentNameCache:
+        """The shared instrument name cache."""
+        return self._instrument_cache
+
+    @property
+    def api_key(self) -> Optional[str]:
+        """The API key used for authentication."""
+        return self._client.api_key
+
+    @property
+    def base_url(self) -> str:
+        """The base URL for API requests."""
+        return self._client.base_url

alphafeed/models.py

@@ -0,0 +1,101 @@
+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"]
+
+AdjustType = Literal["none", "forward", "backward", "forward_additive", "backward_additive"]
+
+
+class CompactKlineData(TypedDict):
+    amount: List[float]
+    close: List[float]
+    high: List[float]
+    low: List[float]
+    open: List[float]
+    prev_close: NotRequired[List[float]]
+    timestamp: List[int]
+    volume: List[int]
+
+
+class ErrorResponse(TypedDict):
+    code: int
+    message: str
+
+
+class ExFactorEntry(TypedDict):
+    ex_factor: float
+    timestamp: int
+
+
+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 InstrumentsBatchRequest(TypedDict):
+    symbols: List[str]
+
+
+class InstrumentsResponse(TypedDict):
+    data: List[Instrument]
+
+
+class KlineBatchResponse(TypedDict):
+    data: Dict[str, CompactKlineData]
+
+
+class KlineResponse(TypedDict):
+    data: CompactKlineData
+
+
+class MarketDepth(TypedDict):
+    ask_prices: List[float]
+    ask_volumes: List[int]
+    bid_prices: List[float]
+    bid_volumes: List[int]
+    region: Literal["CN", "US", "HK"]
+    symbol: str
+    timestamp: int
+
+
+class Quote(TypedDict):
+    amount: float
+    ext: NotRequired[Dict[str, Any]]
+    high: float
+    last_price: float
+    low: float
+    open: float
+    prev_close: float
+    region: Literal["CN", "US", "HK"]
+    symbol: str
+    timestamp: int
+    volume: int
+
+
+class QuotesResponse(TypedDict):
+    data: List[Quote]
+
+
+class RateLimitResponse(TypedDict):
+    code: int
+    message: str
+    retry_after_ms: int
+
+
+class DepthResponse(TypedDict):
+    data: MarketDepth

alphafeed/resources/__init__.py

@@ -0,0 +1,13 @@
+"""Resource modules for AlphaFeed API."""
+
+from .depth import Depth
+from .instruments import Instruments
+from .klines import Klines
+from .quotes import Quotes
+
+__all__ = [
+    "Depth",
+    "Instruments",
+    "Klines",
+    "Quotes",
+]

alphafeed/resources/_base.py

@@ -0,0 +1,17 @@
+"""Base resource class for API resources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .._base_client import SyncAPIClient
+
+
+class SyncResource:
+    """Base class for synchronous API resources."""
+
+    _client: "SyncAPIClient"
+
+    def __init__(self, client: "SyncAPIClient") -> None:
+        self._client = client

alphafeed/resources/depth.py

@@ -0,0 +1,44 @@
+"""Market depth (order book) resources for AlphaFeed API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._base import SyncResource
+
+if TYPE_CHECKING:
+    from ..models import MarketDepth
+
+
+class Depth(SyncResource):
+    """Synchronous interface for market depth endpoint.
+
+    Examples
+    --------
+    >>> client = AlphaFeed(api_key="your-key")
+    >>> depth = client.depth.get("600000.SH")
+    >>> print(depth["bid_prices"], depth["ask_prices"])
+    """
+
+    def get(self, symbol: str) -> "MarketDepth":
+        """Get 5-level market depth for a single symbol.
+
+        Parameters
+        ----------
+        symbol : str
+            Symbol code (e.g. "600000.SH").
+
+        Returns
+        -------
+        MarketDepth
+            Market depth data with bid/ask prices and volumes.
+
+        Examples
+        --------
+        >>> depth = client.depth.get("600000.SH")
+        >>> for i in range(5):
+        ...     print(f"Bid {i+1}: {depth['bid_prices'][i]} x {depth['bid_volumes'][i]}")
+        ...     print(f"Ask {i+1}: {depth['ask_prices'][i]} x {depth['ask_volumes'][i]}")
+        """
+        response = self._client.get("/v1/depth", params={"symbol": symbol})
+        return response["data"]

alphafeed/resources/instruments.py

@@ -0,0 +1,99 @@
+"""Instrument resources for AlphaFeed API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Union, overload
+
+from ._base import SyncResource
+
+if TYPE_CHECKING:
+    from ..models import Instrument
+
+
+class Instruments(SyncResource):
+    """Synchronous interface for instrument endpoints.
+
+    Examples
+    --------
+    >>> client = AlphaFeed(api_key="your-key")
+    >>> inst = client.instruments.get("600000.SH")
+    >>> print(f"{inst['symbol']}: {inst['name']}")
+    """
+
+    @overload
+    def get(self, symbol: str) -> "Instrument": ...
+
+    @overload
+    def get(self, symbol: List[str]) -> List["Instrument"]: ...
+
+    def get(
+        self, symbol: Union[str, List[str]]
+    ) -> Union["Instrument", List["Instrument"]]:
+        """Get metadata for one or more instruments.
+
+        Parameters
+        ----------
+        symbol : str or list of str
+            Instrument code(s). Can be a single symbol string or a list of symbols.
+
+        Returns
+        -------
+        Instrument or list of Instrument
+            If a single symbol is provided, returns a single Instrument dict.
+            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
+
+        Examples
+        --------
+        >>> # Single instrument
+        >>> inst = client.instruments.get("600000.SH")
+        >>> print(inst['name'])
+
+        >>> # Multiple instruments
+        >>> insts = client.instruments.get(["600000.SH", "AAPL.US"])
+        >>> for i in insts:
+        ...     print(f"{i['symbol']}: {i['name']}")
+        """
+        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}
+            )
+            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).
+
+        Returns
+        -------
+        list of Instrument
+            List of instrument metadata dicts.
+
+        Examples
+        --------
+        >>> insts = client.instruments.batch(["600000.SH", "000001.SZ", "AAPL.US"])
+        >>> for i in insts:
+        ...     print(f"{i['symbol']}: {i['name']}")
+        """
+        response = self._client.post(
+            "/v1/instruments/batch", json={"symbols": symbols}
+        )
+        return response["data"]