tickflow 0.1.0__tar.gz

tickflow-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: tickflow
+Version: 0.1.0
+Summary: TickFlow Python Client - High-performance market data API for A-shares, US stocks, and Hong Kong stocks
+Author: TickFlow Team
+License: MIT
+Project-URL: Homepage, https://tickflow.org
+Project-URL: Documentation, https://docs.tickflow.org
+Project-URL: Repository, https://github.com/tickflow/tickflow-python
+Keywords: finance,market-data,stocks,trading,api-client,async
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3.0; extra == "pandas"
+Provides-Extra: all
+Requires-Dist: pandas>=1.3.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator[http]>=0.45.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"

tickflow-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "tickflow"
+version = "0.1.0"
+description = "TickFlow Python Client - High-performance market data API for A-shares, US stocks, and Hong Kong stocks"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "TickFlow Team" }
+]
+keywords = ["finance", "market-data", "stocks", "trading", "api-client", "async"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "httpx>=0.28.1",
+    "pandas>=1.3.0",
+    "typing-extensions>=4.0.0",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.3.0"]
+all = ["pandas>=1.3.0"]
+dev = [
+    "datamodel-code-generator[http]>=0.45.0",
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://tickflow.org"
+Documentation = "https://docs.tickflow.org"
+Repository = "https://github.com/tickflow/tickflow-python"
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tickflow*"]
+
+[tool.setuptools.package-data]
+tickflow = ["py.typed"]
+
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

tickflow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tickflow-0.1.0/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-0.1.0/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,
+        )