tickflow 0.1.0__py3-none-any.whl

tickflow/resources/quotes.py

@@ -0,0 +1,397 @@
+"""Real-time quote resources for TickFlow API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, List, Literal, Optional, Union, overload
+
+from .._types import NOT_GIVEN, NotGiven
+from ._base import AsyncResource, SyncResource
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+    from ..generated_model 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.
+    """
+    import pandas as pd
+
+    if not data:
+        return pd.DataFrame()
+
+    df = pd.DataFrame(data)
+    df["timestamp"] = pd.to_datetime(df["timestamp"], unit="ms")
+    df.set_index("symbol", inplace=True)
+
+    return df
+
+
+class Quotes(SyncResource):
+    """Synchronous interface for real-time quote endpoints.
+
+    Supports querying quotes by symbol codes or universe IDs.
+
+    Examples
+    --------
+    >>> client = TickFlow(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_Equity_A"])
+    """
+
+    @overload
+    def get(
+        self,
+        *,
+        symbols: Union[List[str], str, None] = None,
+        universes: Union[List[str], str, None] = None,
+        as_dataframe: Literal[False] = False,
+    ) -> List["Quote"]: ...
+
+    @overload
+    def get(
+        self,
+        *,
+        symbols: Union[List[str], str, None] = None,
+        universes: Union[List[str], str, None] = None,
+        as_dataframe: Literal[True],
+    ) -> "pd.DataFrame": ...
+
+    def get(
+        self,
+        *,
+        symbols: Union[List[str], str, None] = None,
+        universes: Union[List[str], str, None] = None,
+        as_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.
+        as_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)
+            - session: Trading session status
+            - 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_Equity_A", as_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"
+            )
+
+        # Determine whether to use GET (small query) or POST (large query)
+        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:
+                # Use GET for small queries
+                response = self._client.get(
+                    "/v1/quotes", params={"symbols": ",".join(symbols_list)}
+                )
+            else:
+                # Use POST for large queries
+                response = self._client.post(
+                    "/v1/quotes", json={"symbols": symbols_list}
+                )
+        else:
+            # Universe query
+            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 as_dataframe:
+            return _quotes_to_dataframe(data)
+        return data
+
+    def get_by_symbols(
+        self,
+        symbols: List[str],
+        *,
+        as_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.
+        as_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 as_dataframe:
+            return _quotes_to_dataframe(data)
+        return data
+
+    def get_by_universes(
+        self,
+        universes: List[str],
+        *,
+        as_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.
+        as_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_Equity_A"], as_dataframe=True)
+        """
+        response = self._client.post("/v1/quotes", json={"universes": universes})
+        data = response["data"]
+
+        if as_dataframe:
+            return _quotes_to_dataframe(data)
+        return data
+
+
+class AsyncQuotes(AsyncResource):
+    """Asynchronous interface for real-time quote endpoints.
+
+    Supports querying quotes by symbol codes or universe IDs.
+
+    Examples
+    --------
+    >>> async with AsyncTickFlow(api_key="your-key") as client:
+    ...     quotes = await client.quotes.get(symbols=["600000.SH", "AAPL.US"])
+    """
+
+    @overload
+    async def get(
+        self,
+        *,
+        symbols: Union[List[str], str, None] = None,
+        universes: Union[List[str], str, None] = None,
+        as_dataframe: Literal[False] = False,
+    ) -> List["Quote"]: ...
+
+    @overload
+    async def get(
+        self,
+        *,
+        symbols: Union[List[str], str, None] = None,
+        universes: Union[List[str], str, None] = None,
+        as_dataframe: Literal[True],
+    ) -> "pd.DataFrame": ...
+
+    async def get(
+        self,
+        *,
+        symbols: Union[List[str], str, None] = None,
+        universes: Union[List[str], str, None] = None,
+        as_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.
+        universes : str or list of str, optional
+            Universe ID(s) to query.
+        as_dataframe : bool, optional
+            If True, return a pandas DataFrame indexed by symbol.
+
+        Returns
+        -------
+        list of Quote or pd.DataFrame
+            Quote data for the requested symbols.
+
+        Examples
+        --------
+        >>> quotes = await client.quotes.get(symbols=["600000.SH", "AAPL.US"])
+        >>> df = await client.quotes.get(universes="CN_Equity_A", as_dataframe=True)
+        """
+        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 = await self._client.get(
+                    "/v1/quotes", params={"symbols": ",".join(symbols_list)}
+                )
+            else:
+                response = await 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 = await self._client.get(
+                    "/v1/quotes", params={"universes": ",".join(universes_list)}
+                )
+            else:
+                response = await self._client.post(
+                    "/v1/quotes", json={"universes": universes_list}
+                )
+
+        data = response["data"]
+
+        if as_dataframe:
+            return _quotes_to_dataframe(data)
+        return data
+
+    async def get_by_symbols(
+        self,
+        symbols: List[str],
+        *,
+        as_dataframe: bool = False,
+    ) -> Union[List["Quote"], "pd.DataFrame"]:
+        """Get real-time quotes for a list of symbols.
+
+        Parameters
+        ----------
+        symbols : list of str
+            List of symbol codes.
+        as_dataframe : bool, optional
+            If True, return a pandas DataFrame.
+
+        Returns
+        -------
+        list of Quote or pd.DataFrame
+            Quote data for the requested symbols.
+        """
+        response = await self._client.post("/v1/quotes", json={"symbols": symbols})
+        data = response["data"]
+
+        if as_dataframe:
+            return _quotes_to_dataframe(data)
+        return data
+
+    async def get_by_universes(
+        self,
+        universes: List[str],
+        *,
+        as_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.
+        as_dataframe : bool, optional
+            If True, return a pandas DataFrame.
+
+        Returns
+        -------
+        list of Quote or pd.DataFrame
+            Quote data for all symbols in the universes.
+        """
+        response = await self._client.post("/v1/quotes", json={"universes": universes})
+        data = response["data"]
+
+        if as_dataframe:
+            return _quotes_to_dataframe(data)
+        return data

tickflow/resources/symbols.py

@@ -0,0 +1,176 @@
+"""Symbol metadata resources for TickFlow API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Union, overload
+
+from ._base import AsyncResource, SyncResource
+
+if TYPE_CHECKING:
+    from ..generated_model import SymbolMeta
+
+
+class Symbols(SyncResource):
+    """Synchronous interface for symbol metadata endpoints.
+
+    Examples
+    --------
+    >>> client = TickFlow(api_key="your-key")
+    >>> meta = client.symbols.get("600000.SH")
+    >>> print(f"{meta['symbol']}: {meta['name']}")
+    """
+
+    @overload
+    def get(self, symbol: str) -> "SymbolMeta": ...
+
+    @overload
+    def get(self, symbol: List[str]) -> List["SymbolMeta"]: ...
+
+    def get(
+        self, symbol: Union[str, List[str]]
+    ) -> Union["SymbolMeta", List["SymbolMeta"]]:
+        """Get metadata for one or more symbols.
+
+        Parameters
+        ----------
+        symbol : str or list of str
+            Symbol code(s). Can be a single symbol string or a list of symbols.
+
+        Returns
+        -------
+        SymbolMeta or list of SymbolMeta
+            If a single symbol is provided, returns a single SymbolMeta dict.
+            If a list is provided, returns a list of SymbolMeta dicts.
+
+            Each SymbolMeta 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: Symbol name
+            - symbol_type: Type (stock, etf, index, etc.)
+            - ext: Market-specific extension data
+
+        Examples
+        --------
+        >>> # Single symbol
+        >>> meta = client.symbols.get("600000.SH")
+        >>> print(meta['name'])
+
+        >>> # Multiple symbols
+        >>> metas = client.symbols.get(["600000.SH", "AAPL.US"])
+        >>> for m in metas:
+        ...     print(f"{m['symbol']}: {m['name']}")
+        """
+        if isinstance(symbol, str):
+            response = self._client.get("/v1/symbols", params={"symbols": symbol})
+            data = response["data"]
+            return data[0] if data else {}
+        else:
+            # Use POST for batch queries
+            response = self._client.post("/v1/symbols", json={"symbols": symbol})
+            return response["data"]
+
+    def batch(self, symbols: List[str]) -> List["SymbolMeta"]:
+        """Get metadata for multiple symbols.
+
+        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 SymbolMeta
+            List of symbol metadata dicts.
+
+        Examples
+        --------
+        >>> metas = client.symbols.batch(["600000.SH", "000001.SZ", "AAPL.US"])
+        >>> for m in metas:
+        ...     print(f"{m['symbol']}: {m['name']}")
+        """
+        response = self._client.post("/v1/symbols", json={"symbols": symbols})
+        return response["data"]
+
+
+class AsyncSymbols(AsyncResource):
+    """Asynchronous interface for symbol metadata endpoints.
+
+    Examples
+    --------
+    >>> async with AsyncTickFlow(api_key="your-key") as client:
+    ...     meta = await client.symbols.get("600000.SH")
+    """
+
+    @overload
+    async def get(self, symbol: str) -> "SymbolMeta": ...
+
+    @overload
+    async def get(self, symbol: List[str]) -> List["SymbolMeta"]: ...
+
+    async def get(
+        self, symbol: Union[str, List[str]]
+    ) -> Union["SymbolMeta", List["SymbolMeta"]]:
+        """Get metadata for one or more symbols.
+
+        Parameters
+        ----------
+        symbol : str or list of str
+            Symbol code(s). Can be a single symbol string or a list of symbols.
+
+        Returns
+        -------
+        SymbolMeta or list of SymbolMeta
+            If a single symbol is provided, returns a single SymbolMeta dict.
+            If a list is provided, returns a list of SymbolMeta dicts.
+
+            Each SymbolMeta 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: Symbol name
+            - symbol_type: Type (stock, etf, index, etc.)
+            - ext: Market-specific extension data
+
+        Examples
+        --------
+        >>> # Single symbol
+        >>> meta = await client.symbols.get("600000.SH")
+        >>> print(meta['name'])
+
+        >>> # Multiple symbols
+        >>> metas = await client.symbols.get(["600000.SH", "AAPL.US"])
+        """
+        if isinstance(symbol, str):
+            response = await self._client.get("/v1/symbols", params={"symbols": symbol})
+            data = response["data"]
+            return data[0] if data else {}
+        else:
+            response = await self._client.post("/v1/symbols", json={"symbols": symbol})
+            return response["data"]
+
+    async def batch(self, symbols: List[str]) -> List["SymbolMeta"]:
+        """Get metadata for multiple symbols.
+
+        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 SymbolMeta
+            List of symbol metadata dicts.
+
+        Examples
+        --------
+        >>> metas = await client.symbols.batch(["600000.SH", "000001.SZ", "AAPL.US"])
+        """
+        response = await self._client.post("/v1/symbols", json={"symbols": symbols})
+        return response["data"]

tickflow/resources/universes.py

@@ -0,0 +1,138 @@
+"""Universe 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 UniverseDetail, UniverseSummary
+
+
+class Universes(SyncResource):
+    """Synchronous interface for universe (symbol pool) endpoints.
+
+    Universes are predefined collections of symbols, such as "A-shares" or "US equities".
+
+    Examples
+    --------
+    >>> client = TickFlow(api_key="your-key")
+    >>> universes = client.universes.list()
+    >>> for u in universes:
+    ...     print(f"{u['id']}: {u['name']} ({u['symbol_count']} symbols)")
+    """
+
+    def list(self) -> List["UniverseSummary"]:
+        """Get list of all available universes.
+
+        Returns
+        -------
+        list of UniverseSummary
+            List of universe summaries containing:
+            - id: Unique identifier (e.g., "CN_Equity_A")
+            - name: Display name
+            - region: Region code
+            - category: Category (equity, etf, index, etc.)
+            - symbol_count: Number of symbols
+            - description: Optional description
+
+        Examples
+        --------
+        >>> universes = client.universes.list()
+        >>> cn_equity = next(u for u in universes if u['id'] == 'CN_Equity_A')
+        >>> print(f"A-shares: {cn_equity['symbol_count']} symbols")
+        """
+        response = self._client.get("/v1/universes")
+        return response["data"]
+
+    def get(self, universe_id: str) -> "UniverseDetail":
+        """Get detailed information for a specific universe.
+
+        Parameters
+        ----------
+        universe_id : str
+            Universe identifier (e.g., "CN_Equity_A", "US_Equity").
+
+        Returns
+        -------
+        UniverseDetail
+            Universe details including the full list of symbols:
+            - id: Unique identifier
+            - name: Display name
+            - region: Region code
+            - category: Category
+            - symbol_count: Number of symbols
+            - symbols: List of symbol codes
+            - description: Optional description
+
+        Examples
+        --------
+        >>> universe = client.universes.get("CN_Equity_A")
+        >>> print(f"Found {len(universe['symbols'])} A-share symbols")
+        """
+        response = self._client.get(f"/v1/universes/{universe_id}")
+        return response["data"]
+
+
+class AsyncUniverses(AsyncResource):
+    """Asynchronous interface for universe (symbol pool) endpoints.
+
+    Universes are predefined collections of symbols, such as "A-shares" or "US equities".
+
+    Examples
+    --------
+    >>> async with AsyncTickFlow(api_key="your-key") as client:
+    ...     universes = await client.universes.list()
+    """
+
+    async def list(self) -> List["UniverseSummary"]:
+        """Get list of all available universes.
+
+        Returns
+        -------
+        list of UniverseSummary
+            List of universe summaries containing:
+            - id: Unique identifier (e.g., "CN_Equity_A")
+            - name: Display name
+            - region: Region code
+            - category: Category (equity, etf, index, etc.)
+            - symbol_count: Number of symbols
+            - description: Optional description
+
+        Examples
+        --------
+        >>> universes = await client.universes.list()
+        >>> cn_equity = next(u for u in universes if u['id'] == 'CN_Equity_A')
+        >>> print(f"A-shares: {cn_equity['symbol_count']} symbols")
+        """
+        response = await self._client.get("/v1/universes")
+        return response["data"]
+
+    async def get(self, universe_id: str) -> "UniverseDetail":
+        """Get detailed information for a specific universe.
+
+        Parameters
+        ----------
+        universe_id : str
+            Universe identifier (e.g., "CN_Equity_A", "US_Equity").
+
+        Returns
+        -------
+        UniverseDetail
+            Universe details including the full list of symbols:
+            - id: Unique identifier
+            - name: Display name
+            - region: Region code
+            - category: Category
+            - symbol_count: Number of symbols
+            - symbols: List of symbol codes
+            - description: Optional description
+
+        Examples
+        --------
+        >>> universe = await client.universes.get("CN_Equity_A")
+        >>> print(f"Found {len(universe['symbols'])} A-share symbols")
+        """
+        response = await self._client.get(f"/v1/universes/{universe_id}")
+        return response["data"]