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

tickflow/__init__.py

@@ -1,40 +1,27 @@
-"""TickFlow Python SDK - Market Data API Client.
+"""TickFlow Python SDK - 高性能行情数据客户端。
 
-A high-quality Python client for TickFlow market data API, supporting
-A-shares (China), US stocks, and Hong Kong stocks.
+支持 A股、美股、港股的行情数据查询，提供同步和异步两种接口。
+
+Examples
+--------
+同步使用:
 
-Quick Start
------------
 >>> from tickflow import TickFlow
->>>
->>> # Initialize client
 >>> client = TickFlow(api_key="your-api-key")
->>>
->>> # Get K-line data as pandas DataFrame
->>> df = client.klines.get("600000.SH", period="1d", count=100, as_dataframe=True)
+>>> df = client.klines.get("600000.SH", 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']}")
 
-Async Usage
------------
+异步使用:
+
 >>> import asyncio
 >>> from tickflow import AsyncTickFlow
 >>>
 >>> async def main():
 ...     async with AsyncTickFlow(api_key="your-api-key") as client:
-...         df = await client.klines.get("AAPL.US", as_dataframe=True)
+...         df = await client.klines.get("600000.SH", as_dataframe=True)
 ...         print(df.tail())
 >>>
 >>> asyncio.run(main())
-
-Environment Variables
----------------------
-- TICKFLOW_API_KEY: API key for authentication
-- TICKFLOW_BASE_URL: Custom base URL (optional)
 """
 
 from ._exceptions import (
@@ -49,38 +36,15 @@ from ._exceptions import (
     TickFlowError,
     TimeoutError,
 )
-from ._types import NOT_GIVEN, NotGiven
 from .client import AsyncTickFlow, TickFlow
-
-# Re-export generated types for convenience
-from .generated_model import (  # Core types; K-line types; Quote types; Symbol types; Exchange types; Universe types; Error types
-    ApiError,
-    BidAsk,
-    CNQuoteExt,
-    CNSymbolExt,
+from .generated_model import (
     CompactKlineData,
-    ExchangeListResponse,
-    ExchangeSummary,
-    ExchangeSymbolsResponse,
-    HKQuoteExt,
-    HKSymbolExt,
-    Kline,
-    KlinesBatchResponse,
-    KlinesResponse,
+    Instrument,
+    InstrumentType,
     Period,
     Quote,
-    QuotesResponse,
     Region,
     SessionStatus,
-    SymbolMeta,
-    SymbolMetaResponse,
-    Universe,
-    UniverseDetail,
-    UniverseDetailResponse,
-    UniverseListResponse,
-    UniverseSummary,
-    USQuoteExt,
-    USSymbolExt,
 )
 
 __version__ = "0.1.0"
@@ -100,37 +64,12 @@ __all__ = [
     "InternalServerError",
     "ConnectionError",
     "TimeoutError",
-    # Sentinel
-    "NOT_GIVEN",
-    "NotGiven",
-    # Generated types
+    # Types
+    "CompactKlineData",
+    "Instrument",
+    "InstrumentType",
     "Period",
+    "Quote",
     "Region",
     "SessionStatus",
-    "CompactKlineData",
-    "Kline",
-    "KlinesResponse",
-    "KlinesBatchResponse",
-    "Quote",
-    "QuotesResponse",
-    "BidAsk",
-    "CNQuoteExt",
-    "USQuoteExt",
-    "HKQuoteExt",
-    "SymbolMeta",
-    "SymbolMetaResponse",
-    "CNSymbolExt",
-    "USSymbolExt",
-    "HKSymbolExt",
-    "ExchangeSummary",
-    "ExchangeListResponse",
-    "ExchangeSymbolsResponse",
-    "Universe",
-    "UniverseSummary",
-    "UniverseDetail",
-    "UniverseListResponse",
-    "UniverseDetailResponse",
-    "ApiError",
-    # Version
-    "__version__",
 ]

tickflow/_base_client.py

@@ -1,23 +1,86 @@
-"""Base HTTP client implementation for sync and async operations."""
+"""Base HTTP client implementation with retry support for sync and async operations."""
 
 from __future__ import annotations
 
+import asyncio
 import os
-from typing import Any, Generic, Optional, TypeVar, Union
+import random
+import time
+from typing import Any, Callable, Optional, TypeVar, Union
 
 import httpx
 
-from ._exceptions import ConnectionError, TimeoutError, raise_for_status
-from ._types import NOT_GIVEN, Headers, NotGiven, Query, Timeout, strip_not_given
+from ._exceptions import (
+    APIError,
+    ConnectionError,
+    InternalServerError,
+    RateLimitError,
+    TimeoutError,
+    raise_for_status,
+)
+from ._types import NOT_GIVEN, Headers, NotGiven, Query, Timeout
 
 __all__ = ["SyncAPIClient", "AsyncAPIClient"]
 
 DEFAULT_BASE_URL = "https://api.tickflow.org"
 DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
 
 T = TypeVar("T")
 
 
+def _should_retry(exception: Exception) -> bool:
+    """Determine if an exception is retryable.
+
+    Parameters
+    ----------
+    exception : Exception
+        The exception to check.
+
+    Returns
+    -------
+    bool
+        True if the request should be retried.
+    """
+    # Retry on connection errors and timeouts
+    if isinstance(exception, (ConnectionError, TimeoutError)):
+        return True
+
+    # Retry on server errors (5xx) and rate limits (429)
+    if isinstance(exception, (InternalServerError, RateLimitError)):
+        return True
+
+    return False
+
+
+def _calculate_retry_delay(
+    attempt: int, base_delay: float = 1.0, max_delay: float = 30.0
+) -> float:
+    """Calculate exponential backoff delay with jitter.
+
+    Parameters
+    ----------
+    attempt : int
+        Current attempt number (0-indexed).
+    base_delay : float
+        Base delay in seconds.
+    max_delay : float
+        Maximum delay in seconds.
+
+    Returns
+    -------
+    float
+        Delay in seconds.
+    """
+    # Exponential backoff: 1s, 2s, 4s, 8s, ...
+    delay = base_delay * (2**attempt)
+    # Add jitter (±25%)
+    jitter = delay * 0.25 * (2 * random.random() - 1)
+    delay = delay + jitter
+    # Cap at max delay
+    return min(delay, max_delay)
+
+
 class BaseClient:
     """Base class with shared configuration for API clients."""
 
@@ -26,6 +89,7 @@ class BaseClient:
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
         timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Optional[Headers] = None,
     ) -> None:
         self.api_key = api_key or os.environ.get("TICKFLOW_API_KEY")
@@ -38,6 +102,7 @@ class BaseClient:
             base_url or os.environ.get("TICKFLOW_BASE_URL") or DEFAULT_BASE_URL
         ).rstrip("/")
         self.timeout = timeout
+        self.max_retries = max_retries
         self._default_headers = dict(default_headers) if default_headers else {}
 
     def _build_headers(self, extra_headers: Optional[Headers] = None) -> dict[str, str]:
@@ -58,7 +123,7 @@ class BaseClient:
 
 
 class SyncAPIClient(BaseClient):
-    """Synchronous HTTP client for TickFlow API.
+    """Synchronous HTTP client for TickFlow API with automatic retry.
 
     Parameters
     ----------
@@ -69,6 +134,10 @@ class SyncAPIClient(BaseClient):
         Base URL for the API. Defaults to https://api.tickflow.org.
     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, server errors (5xx),
+        and rate limits (429).
     default_headers : dict, optional
         Default headers to include in all requests.
 
@@ -83,9 +152,10 @@ class SyncAPIClient(BaseClient):
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
         timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Optional[Headers] = None,
     ) -> None:
-        super().__init__(api_key, base_url, timeout, default_headers)
+        super().__init__(api_key, base_url, timeout, max_retries, default_headers)
         self._client = httpx.Client(timeout=timeout)
 
     def __enter__(self) -> "SyncAPIClient":
@@ -107,8 +177,9 @@ class SyncAPIClient(BaseClient):
         json: Optional[dict[str, Any]] = None,
         extra_headers: Optional[Headers] = None,
         timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
     ) -> Any:
-        """Make an HTTP request and return the JSON response.
+        """Make an HTTP request with automatic retry on failures.
 
         Parameters
         ----------
@@ -124,6 +195,8 @@ class SyncAPIClient(BaseClient):
             Additional headers for this request.
         timeout : float, optional
             Override timeout for this request.
+        max_retries : int, optional
+            Override max retries for this request.
 
         Returns
         -------
@@ -133,44 +206,67 @@ class SyncAPIClient(BaseClient):
         Raises
         ------
         APIError
-            If the API returns an error response.
+            If the API returns an error response after all retries.
         ConnectionError
-            If there's a network connection issue.
+            If there's a network connection issue after all retries.
         TimeoutError
-            If the request times out.
+            If the request times out after all retries.
         """
         url = self._build_url(path)
         headers = self._build_headers(extra_headers)
         request_timeout = timeout if not isinstance(timeout, NotGiven) else self.timeout
+        retries = (
+            max_retries if not isinstance(max_retries, NotGiven) else self.max_retries
+        )
 
         # Filter out None values from params
         if params:
             params = {k: v for k, v in params.items() if v is not None}
 
-        try:
-            response = self._client.request(
-                method,
-                url,
-                params=params,
-                json=json,
-                headers=headers,
-                timeout=request_timeout,
-            )
-        except httpx.ConnectError as e:
-            raise ConnectionError(f"Failed to connect to {url}: {e}") from e
-        except httpx.TimeoutException as e:
-            raise TimeoutError(f"Request to {url} timed out") from e
-
-        # Parse response
-        try:
-            response_body = response.json()
-        except Exception:
-            response_body = {"message": response.text, "code": "PARSE_ERROR"}
-
-        # Check for errors
-        raise_for_status(response.status_code, response_body)
-
-        return response_body
+        last_exception: Optional[Exception] = None
+
+        for attempt in range(retries + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json,
+                    headers=headers,
+                    timeout=request_timeout,
+                )
+
+                # Parse response
+                try:
+                    response_body = response.json()
+                except Exception:
+                    response_body = {"message": response.text, "code": "PARSE_ERROR"}
+
+                # Check for errors (may raise retryable exceptions)
+                raise_for_status(response.status_code, response_body)
+
+                return response_body
+
+            except httpx.ConnectError as e:
+                last_exception = ConnectionError(f"Failed to connect to {url}: {e}")
+            except httpx.TimeoutException as e:
+                last_exception = TimeoutError(f"Request to {url} timed out")
+            except APIError as e:
+                last_exception = e
+                if not _should_retry(e):
+                    raise
+
+            # Check if we should retry
+            if attempt < retries and _should_retry(last_exception):
+                delay = _calculate_retry_delay(attempt)
+                time.sleep(delay)
+            else:
+                break
+
+        # All retries exhausted
+        if last_exception:
+            raise last_exception
+        raise RuntimeError("Unexpected state: no exception but request failed")
 
     def get(
         self,
@@ -179,10 +275,16 @@ class SyncAPIClient(BaseClient):
         params: Optional[Query] = None,
         extra_headers: Optional[Headers] = None,
         timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
     ) -> Any:
-        """Make a GET request."""
+        """Make a GET request with automatic retry."""
         return self._request(
-            "GET", path, params=params, extra_headers=extra_headers, timeout=timeout
+            "GET",
+            path,
+            params=params,
+            extra_headers=extra_headers,
+            timeout=timeout,
+            max_retries=max_retries,
         )
 
     def post(
@@ -193,8 +295,9 @@ class SyncAPIClient(BaseClient):
         params: Optional[Query] = None,
         extra_headers: Optional[Headers] = None,
         timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
     ) -> Any:
-        """Make a POST request."""
+        """Make a POST request with automatic retry."""
         return self._request(
             "POST",
             path,
@@ -202,11 +305,12 @@ class SyncAPIClient(BaseClient):
             params=params,
             extra_headers=extra_headers,
             timeout=timeout,
+            max_retries=max_retries,
         )
 
 
 class AsyncAPIClient(BaseClient):
-    """Asynchronous HTTP client for TickFlow API.
+    """Asynchronous HTTP client for TickFlow API with automatic retry.
 
     Parameters
     ----------
@@ -217,6 +321,10 @@ class AsyncAPIClient(BaseClient):
         Base URL for the API. Defaults to https://api.tickflow.org.
     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, server errors (5xx),
+        and rate limits (429).
     default_headers : dict, optional
         Default headers to include in all requests.
 
@@ -231,9 +339,10 @@ class AsyncAPIClient(BaseClient):
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
         timeout: Timeout = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Optional[Headers] = None,
     ) -> None:
-        super().__init__(api_key, base_url, timeout, default_headers)
+        super().__init__(api_key, base_url, timeout, max_retries, default_headers)
         self._client = httpx.AsyncClient(timeout=timeout)
 
     async def __aenter__(self) -> "AsyncAPIClient":
@@ -255,8 +364,9 @@ class AsyncAPIClient(BaseClient):
         json: Optional[dict[str, Any]] = None,
         extra_headers: Optional[Headers] = None,
         timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
     ) -> Any:
-        """Make an async HTTP request and return the JSON response.
+        """Make an async HTTP request with automatic retry on failures.
 
         Parameters
         ----------
@@ -272,6 +382,8 @@ class AsyncAPIClient(BaseClient):
             Additional headers for this request.
         timeout : float, optional
             Override timeout for this request.
+        max_retries : int, optional
+            Override max retries for this request.
 
         Returns
         -------
@@ -281,44 +393,67 @@ class AsyncAPIClient(BaseClient):
         Raises
         ------
         APIError
-            If the API returns an error response.
+            If the API returns an error response after all retries.
         ConnectionError
-            If there's a network connection issue.
+            If there's a network connection issue after all retries.
         TimeoutError
-            If the request times out.
+            If the request times out after all retries.
         """
         url = self._build_url(path)
         headers = self._build_headers(extra_headers)
         request_timeout = timeout if not isinstance(timeout, NotGiven) else self.timeout
+        retries = (
+            max_retries if not isinstance(max_retries, NotGiven) else self.max_retries
+        )
 
         # Filter out None values from params
         if params:
             params = {k: v for k, v in params.items() if v is not None}
 
-        try:
-            response = await self._client.request(
-                method,
-                url,
-                params=params,
-                json=json,
-                headers=headers,
-                timeout=request_timeout,
-            )
-        except httpx.ConnectError as e:
-            raise ConnectionError(f"Failed to connect to {url}: {e}") from e
-        except httpx.TimeoutException as e:
-            raise TimeoutError(f"Request to {url} timed out") from e
-
-        # Parse response
-        try:
-            response_body = response.json()
-        except Exception:
-            response_body = {"message": response.text, "code": "PARSE_ERROR"}
-
-        # Check for errors
-        raise_for_status(response.status_code, response_body)
-
-        return response_body
+        last_exception: Optional[Exception] = None
+
+        for attempt in range(retries + 1):
+            try:
+                response = await self._client.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json,
+                    headers=headers,
+                    timeout=request_timeout,
+                )
+
+                # Parse response
+                try:
+                    response_body = response.json()
+                except Exception:
+                    response_body = {"message": response.text, "code": "PARSE_ERROR"}
+
+                # Check for errors (may raise retryable exceptions)
+                raise_for_status(response.status_code, response_body)
+
+                return response_body
+
+            except httpx.ConnectError as e:
+                last_exception = ConnectionError(f"Failed to connect to {url}: {e}")
+            except httpx.TimeoutException as e:
+                last_exception = TimeoutError(f"Request to {url} timed out")
+            except APIError as e:
+                last_exception = e
+                if not _should_retry(e):
+                    raise
+
+            # Check if we should retry
+            if attempt < retries and _should_retry(last_exception):
+                delay = _calculate_retry_delay(attempt)
+                await asyncio.sleep(delay)
+            else:
+                break
+
+        # All retries exhausted
+        if last_exception:
+            raise last_exception
+        raise RuntimeError("Unexpected state: no exception but request failed")
 
     async def get(
         self,
@@ -327,10 +462,16 @@ class AsyncAPIClient(BaseClient):
         params: Optional[Query] = None,
         extra_headers: Optional[Headers] = None,
         timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
     ) -> Any:
-        """Make an async GET request."""
+        """Make an async GET request with automatic retry."""
         return await self._request(
-            "GET", path, params=params, extra_headers=extra_headers, timeout=timeout
+            "GET",
+            path,
+            params=params,
+            extra_headers=extra_headers,
+            timeout=timeout,
+            max_retries=max_retries,
         )
 
     async def post(
@@ -341,8 +482,9 @@ class AsyncAPIClient(BaseClient):
         params: Optional[Query] = None,
         extra_headers: Optional[Headers] = None,
         timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
     ) -> Any:
-        """Make an async POST request."""
+        """Make an async POST request with automatic retry."""
         return await self._request(
             "POST",
             path,
@@ -350,4 +492,5 @@ class AsyncAPIClient(BaseClient):
             params=params,
             extra_headers=extra_headers,
             timeout=timeout,
+            max_retries=max_retries,
         )