tickflow 0.1.0__py3-none-any.whl

tickflow/client.py

@@ -0,0 +1,264 @@
+"""Main client classes for TickFlow API.
+
+This module provides the primary interfaces for interacting with the TickFlow API:
+- `TickFlow`: Synchronous client
+- `AsyncTickFlow`: Asynchronous client
+
+Both clients provide access to the same resources with consistent method signatures.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ._base_client import AsyncAPIClient, SyncAPIClient
+from ._types import Headers, Timeout
+from .resources import (
+    AsyncExchanges,
+    AsyncKlines,
+    AsyncQuotes,
+    AsyncSymbols,
+    AsyncUniverses,
+    Exchanges,
+    Klines,
+    Quotes,
+    Symbols,
+    Universes,
+)
+
+__all__ = ["TickFlow", "AsyncTickFlow"]
+
+
+class TickFlow:
+    """Synchronous client for TickFlow market data API.
+
+    Provides access to market data including K-lines, quotes, symbol metadata,
+    exchanges, and universes.
+
+    Parameters
+    ----------
+    api_key : str, optional
+        API key for authentication. If not provided, reads from TICKFLOW_API_KEY
+        environment variable.
+    base_url : str, optional
+        Base URL for the API. Defaults to https://api.tickflow.org.
+        Can also be set via TICKFLOW_BASE_URL environment variable.
+    timeout : float, optional
+        Request timeout in seconds. Defaults to 30.0.
+    default_headers : dict, optional
+        Default headers to include in all requests.
+
+    Attributes
+    ----------
+    klines : Klines
+        K-line (OHLCV) data endpoints. Supports DataFrame conversion.
+    quotes : Quotes
+        Real-time quote endpoints.
+    symbols : Symbols
+        Symbol metadata endpoints.
+    exchanges : Exchanges
+        Exchange list endpoints.
+    universes : Universes
+        Universe (symbol pool) endpoints.
+
+    Examples
+    --------
+    Basic usage:
+
+    >>> from tickflow import TickFlow
+    >>>
+    >>> # Initialize client
+    >>> client = TickFlow(api_key="your-api-key")
+    >>>
+    >>> # Get K-line data as DataFrame
+    >>> df = client.klines.get("600000.SH", period="1d", count=100, as_dataframe=True)
+    >>> print(df.tail())
+    >>>
+    >>> # Get real-time quotes
+    >>> quotes = client.quotes.get(symbols=["600000.SH", "AAPL.US"])
+    >>> for q in quotes:
+    ...     print(f"{q['symbol']}: {q['last_price']}")
+
+    Using context manager:
+
+    >>> with TickFlow(api_key="your-api-key") as client:
+    ...     df = client.klines.get("AAPL.US", as_dataframe=True)
+    ...     print(df.tail())
+
+    Using environment variable:
+
+    >>> import os
+    >>> os.environ["TICKFLOW_API_KEY"] = "your-api-key"
+    >>> client = TickFlow()  # Uses TICKFLOW_API_KEY
+    """
+
+    klines: Klines
+    quotes: Quotes
+    symbols: Symbols
+    exchanges: Exchanges
+    universes: Universes
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: Timeout = 30.0,
+        default_headers: Optional[Headers] = None,
+    ) -> None:
+        self._client = SyncAPIClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            default_headers=default_headers,
+        )
+
+        # Initialize resources
+        self.klines = Klines(self._client)
+        self.quotes = Quotes(self._client)
+        self.symbols = Symbols(self._client)
+        self.exchanges = Exchanges(self._client)
+        self.universes = Universes(self._client)
+
+    def __enter__(self) -> "TickFlow":
+        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 api_key(self) -> 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
+
+
+class AsyncTickFlow:
+    """Asynchronous client for TickFlow market data API.
+
+    Provides access to market data including K-lines, quotes, symbol metadata,
+    exchanges, and universes. All methods are async and must be awaited.
+
+    Parameters
+    ----------
+    api_key : str, optional
+        API key for authentication. If not provided, reads from TICKFLOW_API_KEY
+        environment variable.
+    base_url : str, optional
+        Base URL for the API. Defaults to https://api.tickflow.org.
+        Can also be set via TICKFLOW_BASE_URL environment variable.
+    timeout : float, optional
+        Request timeout in seconds. Defaults to 30.0.
+    default_headers : dict, optional
+        Default headers to include in all requests.
+
+    Attributes
+    ----------
+    klines : AsyncKlines
+        K-line (OHLCV) data endpoints. Supports DataFrame conversion.
+    quotes : AsyncQuotes
+        Real-time quote endpoints.
+    symbols : AsyncSymbols
+        Symbol metadata endpoints.
+    exchanges : AsyncExchanges
+        Exchange list endpoints.
+    universes : AsyncUniverses
+        Universe (symbol pool) endpoints.
+
+    Examples
+    --------
+    Basic usage:
+
+    >>> import asyncio
+    >>> from tickflow import AsyncTickFlow
+    >>>
+    >>> async def main():
+    ...     async with AsyncTickFlow(api_key="your-api-key") as client:
+    ...         # Get K-line data as DataFrame
+    ...         df = await client.klines.get("600000.SH", as_dataframe=True)
+    ...         print(df.tail())
+    ...
+    ...         # Get multiple symbols in parallel
+    ...         import asyncio
+    ...         tasks = [
+    ...             client.klines.get(s, as_dataframe=True)
+    ...             for s in ["600000.SH", "000001.SZ", "AAPL.US"]
+    ...         ]
+    ...         results = await asyncio.gather(*tasks)
+    >>>
+    >>> asyncio.run(main())
+
+    Manual resource management:
+
+    >>> async def main():
+    ...     client = AsyncTickFlow(api_key="your-api-key")
+    ...     try:
+    ...         quotes = await client.quotes.get(symbols=["AAPL.US"])
+    ...         print(quotes)
+    ...     finally:
+    ...         await client.close()
+    """
+
+    klines: AsyncKlines
+    quotes: AsyncQuotes
+    symbols: AsyncSymbols
+    exchanges: AsyncExchanges
+    universes: AsyncUniverses
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: Timeout = 30.0,
+        default_headers: Optional[Headers] = None,
+    ) -> None:
+        self._client = AsyncAPIClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            default_headers=default_headers,
+        )
+
+        # Initialize resources
+        self.klines = AsyncKlines(self._client)
+        self.quotes = AsyncQuotes(self._client)
+        self.symbols = AsyncSymbols(self._client)
+        self.exchanges = AsyncExchanges(self._client)
+        self.universes = AsyncUniverses(self._client)
+
+    async def __aenter__(self) -> "AsyncTickFlow":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async 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 an async context manager.
+        """
+        await self._client.close()
+
+    @property
+    def api_key(self) -> 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

tickflow/generated_model.py

@@ -0,0 +1,261 @@
+# generated by datamodel-codegen:
+#   filename:  openapi.json
+#   timestamp: 2026-02-03T10:15:08+00:00
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+from typing_extensions import NotRequired, TypeAlias
+
+
+class ApiError(TypedDict):
+    code: str
+    details: NotRequired[Any]
+    message: str
+
+
+class BidAsk(TypedDict):
+    ask_prices: List[float]
+    ask_volumes: List[int]
+    bid_prices: List[float]
+    bid_volumes: List[int]
+
+
+class CNQuoteExt(TypedDict):
+    bid_ask: NotRequired[Optional[BidAsk]]
+    limit_down: float
+    limit_up: float
+    market_cap: NotRequired[Optional[float]]
+
+
+class CNSymbolExt(TypedDict):
+    delist_date: NotRequired[Optional[int]]
+    down_limit: NotRequired[Optional[float]]
+    float_shares: NotRequired[Optional[float]]
+    is_trading: NotRequired[bool]
+    name_en: NotRequired[Optional[str]]
+    prev_close: NotRequired[Optional[float]]
+    total_shares: NotRequired[Optional[float]]
+    up_limit: NotRequired[Optional[float]]
+
+
+class CompactKlineData(TypedDict):
+    amount: NotRequired[List[float]]
+    close: List[float]
+    high: List[float]
+    low: List[float]
+    open: List[float]
+    timestamp: List[int]
+    volume: List[int]
+
+
+class ExchangeSummary(TypedDict):
+    count: int
+    exchange: str
+    region: str
+
+
+class ExchangeSymbolsResponse(TypedDict):
+    count: int
+    data: List[str]
+    exchange: str
+
+
+class HKQuoteExt(TypedDict):
+    dividend_yield: NotRequired[Optional[float]]
+    lot_size: int
+    spread: NotRequired[Optional[float]]
+
+
+class HKSymbolExt(TypedDict):
+    is_trading: NotRequired[bool]
+    lot_size: NotRequired[Optional[int]]
+    name_cn: NotRequired[Optional[str]]
+    prev_close: NotRequired[Optional[float]]
+
+
+class Kline(TypedDict):
+    amount: NotRequired[float]
+    close: float
+    high: float
+    low: float
+    open: float
+    timestamp: int
+    volume: int
+
+
+class KlinesBatchQuery(TypedDict):
+    count: NotRequired[int]
+    end: NotRequired[Optional[int]]
+    period: str
+    start: NotRequired[Optional[int]]
+    symbols: str
+
+
+class KlinesBatchResponse(TypedDict):
+    data: Dict[str, CompactKlineData]
+
+
+class KlinesQuery(TypedDict):
+    count: NotRequired[int]
+    end: NotRequired[Optional[int]]
+    period: NotRequired[str]
+    start: NotRequired[Optional[int]]
+    symbol: str
+
+
+class KlinesResponse(TypedDict):
+    data: CompactKlineData
+
+
+Period: TypeAlias = Literal[
+    "1m", "5m", "10m", "15m", "30m", "60m", "4h", "1d", "1w", "1M"
+]
+
+
+class QuoteExtension1(CNQuoteExt):
+    type: Literal["CN"]
+
+
+class QuoteExtension3(HKQuoteExt):
+    type: Literal["HK"]
+
+
+class QuotesQuery(TypedDict):
+    symbols: str
+
+
+class QuotesRequest(TypedDict):
+    symbols: List[str]
+
+
+Region: TypeAlias = Literal["CN", "US", "HK"]
+
+
+SessionStatus: TypeAlias = Literal[
+    "pre_market", "regular", "after_hours", "closed", "halted", "lunch_break"
+]
+
+
+class SymbolMetaExt1(CNSymbolExt):
+    type: Literal["CN"]
+
+
+class SymbolMetaExt3(HKSymbolExt):
+    type: Literal["HK"]
+
+
+class SymbolsMetaRequest(TypedDict):
+    symbols: List[str]
+
+
+class SymbolsQuery(TypedDict):
+    symbols: str
+
+
+class USQuoteExt(TypedDict):
+    after_hours_change_pct: NotRequired[Optional[float]]
+    after_hours_price: NotRequired[Optional[float]]
+    avg_volume_30d: NotRequired[Optional[int]]
+    pre_market_change_pct: NotRequired[Optional[float]]
+    pre_market_price: NotRequired[Optional[float]]
+    week52_high: NotRequired[Optional[float]]
+    week52_low: NotRequired[Optional[float]]
+
+
+class USSymbolExt(TypedDict):
+    full_name: NotRequired[Optional[str]]
+    market_cap: NotRequired[Optional[float]]
+    sector: NotRequired[Optional[str]]
+
+
+class Universe(TypedDict):
+    category: str
+    description: NotRequired[Optional[str]]
+    id: str
+    name: str
+    region: str
+    symbols: List[str]
+
+
+class UniverseQuery(TypedDict):
+    universes: str
+
+
+class UniverseSummary(TypedDict):
+    category: str
+    description: NotRequired[Optional[str]]
+    id: str
+    name: str
+    region: str
+    symbol_count: int
+
+
+class ExchangeListResponse(TypedDict):
+    data: List[ExchangeSummary]
+
+
+class QuoteExtension2(USQuoteExt):
+    type: Literal["US"]
+
+
+QuoteExtension: TypeAlias = Union[QuoteExtension1, QuoteExtension2, QuoteExtension3]
+
+
+class SymbolMetaExt2(USSymbolExt):
+    type: Literal["US"]
+
+
+SymbolMetaExt: TypeAlias = Union[SymbolMetaExt1, SymbolMetaExt2, SymbolMetaExt3]
+
+
+class UniverseDetail(UniverseSummary):
+    symbols: List[str]
+
+
+class UniverseDetailResponse(TypedDict):
+    data: UniverseDetail
+
+
+class UniverseListResponse(TypedDict):
+    data: List[UniverseSummary]
+
+
+class Quote(TypedDict):
+    amount: float
+    ext: NotRequired[Optional[QuoteExtension]]
+    high: float
+    last_price: float
+    low: float
+    name: NotRequired[Optional[str]]
+    open: float
+    prev_close: float
+    region: Region
+    session: NotRequired[Optional[SessionStatus]]
+    symbol: str
+    timestamp: int
+    volume: int
+
+
+class QuotesResponse(TypedDict):
+    data: Dict[str, Quote]
+
+
+class SymbolMeta(TypedDict):
+    code: str
+    exchange: str
+    ext: NotRequired[Optional[SymbolMetaExt]]
+    list_date: NotRequired[Optional[int]]
+    name: NotRequired[Optional[str]]
+    region: str
+    symbol: str
+    symbol_type: NotRequired[Optional[str]]
+
+
+class SymbolMetaResponse(TypedDict):
+    data: List[SymbolMeta]
+
+
+class UniverseSnapshotResponse(TypedDict):
+    data: List[Quote]

tickflow/resources/__init__.py

@@ -0,0 +1,20 @@
+"""Resource modules for TickFlow API."""
+
+from .exchanges import AsyncExchanges, Exchanges
+from .klines import AsyncKlines, Klines
+from .quotes import AsyncQuotes, Quotes
+from .symbols import AsyncSymbols, Symbols
+from .universes import AsyncUniverses, Universes
+
+__all__ = [
+    "Exchanges",
+    "AsyncExchanges",
+    "Klines",
+    "AsyncKlines",
+    "Quotes",
+    "AsyncQuotes",
+    "Symbols",
+    "AsyncSymbols",
+    "Universes",
+    "AsyncUniverses",
+]

tickflow/resources/_base.py

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

tickflow/resources/exchanges.py

@@ -0,0 +1,116 @@
+"""Exchange resources for TickFlow API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+from ._base import AsyncResource, SyncResource
+
+if TYPE_CHECKING:
+    from ..generated_model import ExchangeSummary
+
+
+class Exchanges(SyncResource):
+    """Synchronous interface for exchange endpoints.
+
+    Examples
+    --------
+    >>> client = TickFlow(api_key="your-key")
+    >>> exchanges = client.exchanges.list()
+    >>> for exchange in exchanges:
+    ...     print(f"{exchange['exchange']}: {exchange['count']} symbols")
+    """
+
+    def list(self) -> List["ExchangeSummary"]:
+        """Get list of all exchanges with symbol counts.
+
+        Returns
+        -------
+        list of ExchangeSummary
+            List of exchange information containing:
+            - exchange: Exchange code (e.g., "SH", "SZ", "US")
+            - region: Region code (e.g., "CN", "US", "HK")
+            - count: Number of symbols in the exchange
+
+        Examples
+        --------
+        >>> exchanges = client.exchanges.list()
+        >>> print(exchanges)
+        [{'exchange': 'SH', 'region': 'CN', 'count': 2100}, ...]
+        """
+        response = self._client.get("/v1/exchanges")
+        return response["data"]
+
+    def get_symbols(self, exchange: str) -> List[str]:
+        """Get all symbols for a specific exchange.
+
+        Parameters
+        ----------
+        exchange : str
+            Exchange code (e.g., "SH", "SZ", "BJ", "US", "HK").
+
+        Returns
+        -------
+        list of str
+            List of symbol codes.
+
+        Examples
+        --------
+        >>> symbols = client.exchanges.get_symbols("SH")
+        >>> print(symbols[:5])
+        ['600000.SH', '600001.SH', '600002.SH', ...]
+        """
+        response = self._client.get(f"/v1/exchanges/{exchange}/symbols")
+        return response["data"]
+
+
+class AsyncExchanges(AsyncResource):
+    """Asynchronous interface for exchange endpoints.
+
+    Examples
+    --------
+    >>> async with AsyncTickFlow(api_key="your-key") as client:
+    ...     exchanges = await client.exchanges.list()
+    """
+
+    async def list(self) -> List["ExchangeSummary"]:
+        """Get list of all exchanges with symbol counts.
+
+        Returns
+        -------
+        list of ExchangeSummary
+            List of exchange information containing:
+            - exchange: Exchange code (e.g., "SH", "SZ", "US")
+            - region: Region code (e.g., "CN", "US", "HK")
+            - count: Number of symbols in the exchange
+
+        Examples
+        --------
+        >>> exchanges = await client.exchanges.list()
+        >>> print(exchanges)
+        [{'exchange': 'SH', 'region': 'CN', 'count': 2100}, ...]
+        """
+        response = await self._client.get("/v1/exchanges")
+        return response["data"]
+
+    async def get_symbols(self, exchange: str) -> List[str]:
+        """Get all symbols for a specific exchange.
+
+        Parameters
+        ----------
+        exchange : str
+            Exchange code (e.g., "SH", "SZ", "BJ", "US", "HK").
+
+        Returns
+        -------
+        list of str
+            List of symbol codes.
+
+        Examples
+        --------
+        >>> symbols = await client.exchanges.get_symbols("SH")
+        >>> print(symbols[:5])
+        ['600000.SH', '600001.SH', '600002.SH', ...]
+        """
+        response = await self._client.get(f"/v1/exchanges/{exchange}/symbols")
+        return response["data"]