tickflow 0.1.0__py3-none-any.whl

tickflow/__init__.py

@@ -0,0 +1,136 @@
+"""TickFlow Python SDK - Market Data API Client.
+
+A high-quality Python client for TickFlow market data API, supporting
+A-shares (China), US stocks, and Hong Kong stocks.
+
+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)
+>>> 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)
+...         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 (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    InternalServerError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    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,
+    CompactKlineData,
+    ExchangeListResponse,
+    ExchangeSummary,
+    ExchangeSymbolsResponse,
+    HKQuoteExt,
+    HKSymbolExt,
+    Kline,
+    KlinesBatchResponse,
+    KlinesResponse,
+    Period,
+    Quote,
+    QuotesResponse,
+    Region,
+    SessionStatus,
+    SymbolMeta,
+    SymbolMetaResponse,
+    Universe,
+    UniverseDetail,
+    UniverseDetailResponse,
+    UniverseListResponse,
+    UniverseSummary,
+    USQuoteExt,
+    USSymbolExt,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main clients
+    "TickFlow",
+    "AsyncTickFlow",
+    # Exceptions
+    "TickFlowError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "BadRequestError",
+    "RateLimitError",
+    "InternalServerError",
+    "ConnectionError",
+    "TimeoutError",
+    # Sentinel
+    "NOT_GIVEN",
+    "NotGiven",
+    # Generated types
+    "Period",
+    "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

@@ -0,0 +1,353 @@
+"""Base HTTP client implementation for sync and async operations."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Generic, 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
+
+__all__ = ["SyncAPIClient", "AsyncAPIClient"]
+
+DEFAULT_BASE_URL = "https://api.tickflow.org"
+DEFAULT_TIMEOUT = 30.0
+
+T = TypeVar("T")
+
+
+class BaseClient:
+    """Base class with shared configuration for API clients."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        default_headers: Optional[Headers] = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("TICKFLOW_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key is required. Pass `api_key` or set TICKFLOW_API_KEY environment variable."
+            )
+
+        self.base_url = (
+            base_url or os.environ.get("TICKFLOW_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        self._default_headers = dict(default_headers) if default_headers else {}
+
+    def _build_headers(self, extra_headers: Optional[Headers] = None) -> dict[str, str]:
+        """Build request headers with authentication."""
+        headers = {
+            "x-api-key": self.api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            **self._default_headers,
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+        return headers
+
+    def _build_url(self, path: str) -> str:
+        """Build full URL from path."""
+        return f"{self.base_url}{path}"
+
+
+class SyncAPIClient(BaseClient):
+    """Synchronous HTTP client for TickFlow API.
+
+    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.
+    timeout : float, optional
+        Request timeout in seconds. Defaults to 30.0.
+    default_headers : dict, optional
+        Default headers to include in all requests.
+
+    Examples
+    --------
+    >>> client = SyncAPIClient(api_key="your-api-key")
+    >>> response = client.get("/v1/exchanges")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        default_headers: Optional[Headers] = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, default_headers)
+        self._client = httpx.Client(timeout=timeout)
+
+    def __enter__(self) -> "SyncAPIClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Query] = None,
+        json: Optional[dict[str, Any]] = None,
+        extra_headers: Optional[Headers] = None,
+        timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make an HTTP request and return the JSON response.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method (GET, POST, etc.).
+        path : str
+            API endpoint path.
+        params : dict, optional
+            Query parameters.
+        json : dict, optional
+            JSON request body.
+        extra_headers : dict, optional
+            Additional headers for this request.
+        timeout : float, optional
+            Override timeout for this request.
+
+        Returns
+        -------
+        Any
+            Parsed JSON response.
+
+        Raises
+        ------
+        APIError
+            If the API returns an error response.
+        ConnectionError
+            If there's a network connection issue.
+        TimeoutError
+            If the request times out.
+        """
+        url = self._build_url(path)
+        headers = self._build_headers(extra_headers)
+        request_timeout = timeout if not isinstance(timeout, NotGiven) else self.timeout
+
+        # 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
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: Optional[Query] = None,
+        extra_headers: Optional[Headers] = None,
+        timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make a GET request."""
+        return self._request(
+            "GET", path, params=params, extra_headers=extra_headers, timeout=timeout
+        )
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[Query] = None,
+        extra_headers: Optional[Headers] = None,
+        timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make a POST request."""
+        return self._request(
+            "POST",
+            path,
+            json=json,
+            params=params,
+            extra_headers=extra_headers,
+            timeout=timeout,
+        )
+
+
+class AsyncAPIClient(BaseClient):
+    """Asynchronous HTTP client for TickFlow API.
+
+    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.
+    timeout : float, optional
+        Request timeout in seconds. Defaults to 30.0.
+    default_headers : dict, optional
+        Default headers to include in all requests.
+
+    Examples
+    --------
+    >>> async with AsyncAPIClient(api_key="your-api-key") as client:
+    ...     response = await client.get("/v1/exchanges")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Timeout = DEFAULT_TIMEOUT,
+        default_headers: Optional[Headers] = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, default_headers)
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    async def __aenter__(self) -> "AsyncAPIClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Query] = None,
+        json: Optional[dict[str, Any]] = None,
+        extra_headers: Optional[Headers] = None,
+        timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make an async HTTP request and return the JSON response.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method (GET, POST, etc.).
+        path : str
+            API endpoint path.
+        params : dict, optional
+            Query parameters.
+        json : dict, optional
+            JSON request body.
+        extra_headers : dict, optional
+            Additional headers for this request.
+        timeout : float, optional
+            Override timeout for this request.
+
+        Returns
+        -------
+        Any
+            Parsed JSON response.
+
+        Raises
+        ------
+        APIError
+            If the API returns an error response.
+        ConnectionError
+            If there's a network connection issue.
+        TimeoutError
+            If the request times out.
+        """
+        url = self._build_url(path)
+        headers = self._build_headers(extra_headers)
+        request_timeout = timeout if not isinstance(timeout, NotGiven) else self.timeout
+
+        # 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
+
+    async def get(
+        self,
+        path: str,
+        *,
+        params: Optional[Query] = None,
+        extra_headers: Optional[Headers] = None,
+        timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make an async GET request."""
+        return await self._request(
+            "GET", path, params=params, extra_headers=extra_headers, timeout=timeout
+        )
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[Query] = None,
+        extra_headers: Optional[Headers] = None,
+        timeout: Union[Timeout, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make an async POST request."""
+        return await self._request(
+            "POST",
+            path,
+            json=json,
+            params=params,
+            extra_headers=extra_headers,
+            timeout=timeout,
+        )

tickflow/_exceptions.py

@@ -0,0 +1,140 @@
+"""Custom exceptions for the TickFlow SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class TickFlowError(Exception):
+    """Base exception for all TickFlow SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class APIError(TickFlowError):
+    """Error returned by the TickFlow 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(TickFlowError):
+    """Network connection error."""
+
+    pass
+
+
+class TimeoutError(TickFlowError):
+    """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)

tickflow/_types.py

@@ -0,0 +1,60 @@
+"""Custom types and sentinel values for the TickFlow SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping, TypeVar, Union
+
+if TYPE_CHECKING:
+    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()
+
+# Type alias for the sentinel
+NotGiven = _NotGiven
+
+# Type aliases for common parameter types
+Headers = Mapping[str, str]
+Query = Mapping[str, Union[str, int, bool, None]]
+Timeout = Union[float, None]
+
+# Generic type for response models
+T = TypeVar("T")
+
+# Type for DataFrame or raw response
+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)}