tickflow 0.1.0__py3-none-any.whl → 0.1.0.dev1__py3-none-any.whl

tickflow/client.py

@@ -11,18 +11,18 @@ from __future__ import annotations
 
 from typing import Any, Optional
 
-from ._base_client import AsyncAPIClient, SyncAPIClient
+from ._base_client import DEFAULT_MAX_RETRIES, AsyncAPIClient, SyncAPIClient
 from ._types import Headers, Timeout
 from .resources import (
     AsyncExchanges,
+    AsyncInstruments,
     AsyncKlines,
     AsyncQuotes,
-    AsyncSymbols,
     AsyncUniverses,
     Exchanges,
+    Instruments,
     Klines,
     Quotes,
-    Symbols,
     Universes,
 )
 
@@ -32,7 +32,7 @@ __all__ = ["TickFlow", "AsyncTickFlow"]
 class TickFlow:
     """Synchronous client for TickFlow market data API.
 
-    Provides access to market data including K-lines, quotes, symbol metadata,
+    Provides access to market data including K-lines, quotes, instruments,
     exchanges, and universes.
 
     Parameters
@@ -54,8 +54,8 @@ class TickFlow:
         K-line (OHLCV) data endpoints. Supports DataFrame conversion.
     quotes : Quotes
         Real-time quote endpoints.
-    symbols : Symbols
-        Symbol metadata endpoints.
+    instruments : Instruments
+        Instrument metadata endpoints.
     exchanges : Exchanges
         Exchange list endpoints.
     universes : Universes
@@ -94,7 +94,7 @@ class TickFlow:
 
     klines: Klines
     quotes: Quotes
-    symbols: Symbols
+    instruments: Instruments
     exchanges: Exchanges
     universes: Universes
 
@@ -104,19 +104,21 @@ class TickFlow:
         *,
         base_url: Optional[str] = None,
         timeout: Timeout = 30.0,
+        max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Optional[Headers] = None,
     ) -> None:
         self._client = SyncAPIClient(
             api_key=api_key,
             base_url=base_url,
             timeout=timeout,
+            max_retries=max_retries,
             default_headers=default_headers,
         )
 
         # Initialize resources
         self.klines = Klines(self._client)
         self.quotes = Quotes(self._client)
-        self.symbols = Symbols(self._client)
+        self.instruments = Instruments(self._client)
         self.exchanges = Exchanges(self._client)
         self.universes = Universes(self._client)
 
@@ -148,7 +150,7 @@ class TickFlow:
 class AsyncTickFlow:
     """Asynchronous client for TickFlow market data API.
 
-    Provides access to market data including K-lines, quotes, symbol metadata,
+    Provides access to market data including K-lines, quotes, instruments,
     exchanges, and universes. All methods are async and must be awaited.
 
     Parameters
@@ -161,6 +163,9 @@ class AsyncTickFlow:
         Can also be set via TICKFLOW_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.
 
@@ -170,8 +175,8 @@ class AsyncTickFlow:
         K-line (OHLCV) data endpoints. Supports DataFrame conversion.
     quotes : AsyncQuotes
         Real-time quote endpoints.
-    symbols : AsyncSymbols
-        Symbol metadata endpoints.
+    instruments : AsyncInstruments
+        Instrument metadata endpoints.
     exchanges : AsyncExchanges
         Exchange list endpoints.
     universes : AsyncUniverses
@@ -213,7 +218,7 @@ class AsyncTickFlow:
 
     klines: AsyncKlines
     quotes: AsyncQuotes
-    symbols: AsyncSymbols
+    instruments: AsyncInstruments
     exchanges: AsyncExchanges
     universes: AsyncUniverses
 
@@ -223,19 +228,21 @@ class AsyncTickFlow:
         *,
         base_url: Optional[str] = None,
         timeout: Timeout = 30.0,
+        max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Optional[Headers] = None,
     ) -> None:
         self._client = AsyncAPIClient(
             api_key=api_key,
             base_url=base_url,
             timeout=timeout,
+            max_retries=max_retries,
             default_headers=default_headers,
         )
 
         # Initialize resources
         self.klines = AsyncKlines(self._client)
         self.quotes = AsyncQuotes(self._client)
-        self.symbols = AsyncSymbols(self._client)
+        self.instruments = AsyncInstruments(self._client)
         self.exchanges = AsyncExchanges(self._client)
         self.universes = AsyncUniverses(self._client)
 

tickflow/generated_model.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  openapi.json
-#   timestamp: 2026-02-03T10:15:08+00:00
+#   timestamp: 2026-02-03T15:11:44+00:00
 
 from __future__ import annotations
 
@@ -22,14 +22,7 @@ class BidAsk(TypedDict):
     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):
+class CNInstrumentExt(TypedDict):
     delist_date: NotRequired[Optional[int]]
     down_limit: NotRequired[Optional[float]]
     float_shares: NotRequired[Optional[float]]
@@ -40,6 +33,13 @@ class CNSymbolExt(TypedDict):
     up_limit: NotRequired[Optional[float]]
 
 
+class CNQuoteExt(TypedDict):
+    bid_ask: NotRequired[Optional[BidAsk]]
+    limit_down: float
+    limit_up: float
+    market_cap: NotRequired[Optional[float]]
+
+
 class CompactKlineData(TypedDict):
     amount: NotRequired[List[float]]
     close: List[float]
@@ -50,16 +50,21 @@ class CompactKlineData(TypedDict):
     volume: List[int]
 
 
-class ExchangeSummary(TypedDict):
+class ExchangeInfo(TypedDict):
     count: int
     exchange: str
     region: str
 
 
-class ExchangeSymbolsResponse(TypedDict):
-    count: int
-    data: List[str]
-    exchange: str
+class ExchangeListResponse(TypedDict):
+    data: List[ExchangeInfo]
+
+
+class HKInstrumentExt(TypedDict):
+    is_trading: NotRequired[bool]
+    lot_size: NotRequired[Optional[int]]
+    name_cn: NotRequired[Optional[str]]
+    prev_close: NotRequired[Optional[float]]
 
 
 class HKQuoteExt(TypedDict):
@@ -68,11 +73,25 @@ class HKQuoteExt(TypedDict):
     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 InstrumentExt1(CNInstrumentExt):
+    type: Literal["CN"]
+
+
+class InstrumentExt3(HKInstrumentExt):
+    type: Literal["HK"]
+
+
+InstrumentType: TypeAlias = Literal[
+    "stock", "etf", "index", "bond", "fund", "futures", "options", "other"
+]
+
+
+class InstrumentsQuery(TypedDict):
+    symbols: str
+
+
+class InstrumentsRequest(TypedDict):
+    symbols: List[str]
 
 
 class Kline(TypedDict):
@@ -85,26 +104,10 @@ class Kline(TypedDict):
     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
 
@@ -123,11 +126,13 @@ class QuoteExtension3(HKQuoteExt):
 
 
 class QuotesQuery(TypedDict):
-    symbols: str
+    symbols: NotRequired[Optional[str]]
+    universes: NotRequired[Optional[str]]
 
 
 class QuotesRequest(TypedDict):
-    symbols: List[str]
+    symbols: NotRequired[List[str]]
+    universes: NotRequired[List[str]]
 
 
 Region: TypeAlias = Literal["CN", "US", "HK"]
@@ -138,20 +143,10 @@ SessionStatus: TypeAlias = Literal[
 ]
 
 
-class SymbolMetaExt1(CNSymbolExt):
-    type: Literal["CN"]
-
-
-class SymbolMetaExt3(HKSymbolExt):
-    type: Literal["HK"]
-
-
-class SymbolsMetaRequest(TypedDict):
-    symbols: List[str]
-
-
-class SymbolsQuery(TypedDict):
-    symbols: str
+class USInstrumentExt(TypedDict):
+    full_name: NotRequired[Optional[str]]
+    market_cap: NotRequired[Optional[float]]
+    sector: NotRequired[Optional[str]]
 
 
 class USQuoteExt(TypedDict):
@@ -164,12 +159,6 @@ class USQuoteExt(TypedDict):
     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]]
@@ -179,10 +168,6 @@ class Universe(TypedDict):
     symbols: List[str]
 
 
-class UniverseQuery(TypedDict):
-    universes: str
-
-
 class UniverseSummary(TypedDict):
     category: str
     description: NotRequired[Optional[str]]
@@ -192,22 +177,38 @@ class UniverseSummary(TypedDict):
     symbol_count: int
 
 
-class ExchangeListResponse(TypedDict):
-    data: List[ExchangeSummary]
+class ExchangeInstrumentsQuery(TypedDict):
+    type: NotRequired[Optional[InstrumentType]]
 
 
-class QuoteExtension2(USQuoteExt):
+class InstrumentExt2(USInstrumentExt):
     type: Literal["US"]
 
 
-QuoteExtension: TypeAlias = Union[QuoteExtension1, QuoteExtension2, QuoteExtension3]
+InstrumentExt: TypeAlias = Union[InstrumentExt1, InstrumentExt2, InstrumentExt3]
 
 
-class SymbolMetaExt2(USSymbolExt):
+class KlinesBatchQuery(TypedDict):
+    count: NotRequired[int]
+    end_time: NotRequired[Optional[int]]
+    period: NotRequired[Period]
+    start_time: NotRequired[Optional[int]]
+    symbols: str
+
+
+class KlinesQuery(TypedDict):
+    count: NotRequired[int]
+    end_time: NotRequired[Optional[int]]
+    period: NotRequired[Period]
+    start_time: NotRequired[Optional[int]]
+    symbol: str
+
+
+class QuoteExtension2(USQuoteExt):
     type: Literal["US"]
 
 
-SymbolMetaExt: TypeAlias = Union[SymbolMetaExt1, SymbolMetaExt2, SymbolMetaExt3]
+QuoteExtension: TypeAlias = Union[QuoteExtension1, QuoteExtension2, QuoteExtension3]
 
 
 class UniverseDetail(UniverseSummary):
@@ -222,6 +223,20 @@ class UniverseListResponse(TypedDict):
     data: List[UniverseSummary]
 
 
+class Instrument(TypedDict):
+    code: str
+    exchange: str
+    ext: NotRequired[Optional[InstrumentExt]]
+    instrument_type: NotRequired[Optional[InstrumentType]]
+    name: NotRequired[Optional[str]]
+    region: str
+    symbol: str
+
+
+class InstrumentsResponse(TypedDict):
+    data: List[Instrument]
+
+
 class Quote(TypedDict):
     amount: float
     ext: NotRequired[Optional[QuoteExtension]]
@@ -239,23 +254,10 @@ class Quote(TypedDict):
 
 
 class QuotesResponse(TypedDict):
-    data: Dict[str, Quote]
+    data: List[Quote]
 
 
-class SymbolMeta(TypedDict):
-    code: str
+class ExchangeInstrumentsResponse(TypedDict):
+    count: int
+    data: List[Instrument]
     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

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

tickflow/resources/exchanges.py

@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, List
+from typing import TYPE_CHECKING, List, Optional
 
 from ._base import AsyncResource, SyncResource
 
 if TYPE_CHECKING:
-    from ..generated_model import ExchangeSummary
+    from ..generated_model import ExchangeSummary, Instrument, InstrumentType
 
 
 class Exchanges(SyncResource):
@@ -18,11 +18,11 @@ class Exchanges(SyncResource):
     >>> client = TickFlow(api_key="your-key")
     >>> exchanges = client.exchanges.list()
     >>> for exchange in exchanges:
-    ...     print(f"{exchange['exchange']}: {exchange['count']} symbols")
+    ...     print(f"{exchange['exchange']}: {exchange['count']} instruments")
     """
 
     def list(self) -> List["ExchangeSummary"]:
-        """Get list of all exchanges with symbol counts.
+        """Get list of all exchanges with instrument counts.
 
         Returns
         -------
@@ -30,7 +30,7 @@ class Exchanges(SyncResource):
             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
+            - count: Number of instruments in the exchange
 
         Examples
         --------
@@ -41,26 +41,39 @@ class Exchanges(SyncResource):
         response = self._client.get("/v1/exchanges")
         return response["data"]
 
-    def get_symbols(self, exchange: str) -> List[str]:
-        """Get all symbols for a specific exchange.
+    def get_instruments(
+        self, exchange: str, instrument_type: Optional["InstrumentType"] = None
+    ) -> List["Instrument"]:
+        """Get all instruments for a specific exchange.
 
         Parameters
         ----------
         exchange : str
             Exchange code (e.g., "SH", "SZ", "BJ", "US", "HK").
+        instrument_type : InstrumentType, optional
+            Filter by instrument type (stock, etf, index, bond, fund, etc.).
 
         Returns
         -------
-        list of str
-            List of symbol codes.
+        list of Instrument
+            List of instrument metadata.
 
         Examples
         --------
-        >>> symbols = client.exchanges.get_symbols("SH")
-        >>> print(symbols[:5])
-        ['600000.SH', '600001.SH', '600002.SH', ...]
+        >>> # Get all instruments
+        >>> instruments = client.exchanges.get_instruments("SH")
+        >>> print(f"Found {len(instruments)} instruments")
+
+        >>> # Get only ETFs
+        >>> etfs = client.exchanges.get_instruments("SH", instrument_type="etf")
+        >>> print(f"Found {len(etfs)} ETFs")
         """
-        response = self._client.get(f"/v1/exchanges/{exchange}/symbols")
+        params = {}
+        if instrument_type is not None:
+            params["type"] = instrument_type
+        response = self._client.get(
+            f"/v1/exchanges/{exchange}/instruments", params=params or None
+        )
         return response["data"]
 
 
@@ -74,7 +87,7 @@ class AsyncExchanges(AsyncResource):
     """
 
     async def list(self) -> List["ExchangeSummary"]:
-        """Get list of all exchanges with symbol counts.
+        """Get list of all exchanges with instrument counts.
 
         Returns
         -------
@@ -82,7 +95,7 @@ class AsyncExchanges(AsyncResource):
             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
+            - count: Number of instruments in the exchange
 
         Examples
         --------
@@ -93,24 +106,37 @@ class AsyncExchanges(AsyncResource):
         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.
+    async def get_instruments(
+        self, exchange: str, instrument_type: Optional["InstrumentType"] = None
+    ) -> List["Instrument"]:
+        """Get all instruments for a specific exchange.
 
         Parameters
         ----------
         exchange : str
             Exchange code (e.g., "SH", "SZ", "BJ", "US", "HK").
+        instrument_type : InstrumentType, optional
+            Filter by instrument type (stock, etf, index, bond, fund, etc.).
 
         Returns
         -------
-        list of str
-            List of symbol codes.
+        list of Instrument
+            List of instrument metadata.
 
         Examples
         --------
-        >>> symbols = await client.exchanges.get_symbols("SH")
-        >>> print(symbols[:5])
-        ['600000.SH', '600001.SH', '600002.SH', ...]
+        >>> # Get all instruments
+        >>> instruments = await client.exchanges.get_instruments("SH")
+        >>> print(f"Found {len(instruments)} instruments")
+
+        >>> # Get only ETFs
+        >>> etfs = await client.exchanges.get_instruments("SH", instrument_type="etf")
+        >>> print(f"Found {len(etfs)} ETFs")
         """
-        response = await self._client.get(f"/v1/exchanges/{exchange}/symbols")
+        params = {}
+        if instrument_type is not None:
+            params["type"] = instrument_type
+        response = await self._client.get(
+            f"/v1/exchanges/{exchange}/instruments", params=params or None
+        )
         return response["data"]