sharetop 0.1.0__py3-none-any.whl

sharetop/__init__.py

@@ -0,0 +1,38 @@
+"""ShareTop Python SDK - 高性能行情数据客户端。
+
+支持 A股的基础数据和行情数据查询，提供同步和异步两种接口。
+
+"""
+
+from .__version__ import __version__
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    InternalServerError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ShareTopError,
+    TimeoutError,
+)
+from .client import ShareTop
+
+
+__all__ = [
+    "__version__",
+    # Main clients
+    "ShareTop",
+    # Exceptions
+    "ShareTopError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "BadRequestError",
+    "RateLimitError",
+    "InternalServerError",
+    "ConnectionError",
+    "TimeoutError",
+]

sharetop/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sharetop/_base_client.py

@@ -0,0 +1,330 @@
+"""Base HTTP client implementation with retry support for sync and async operations."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from typing import Any, Optional, TypeVar, Union
+
+import httpx
+
+from . import __version__
+from ._exceptions import (
+    APIError,
+    ConnectionError,
+    InternalServerError,
+    RateLimitError,
+    TimeoutError,
+    raise_for_status,
+)
+from ._types import NOT_GIVEN, Headers, NotGiven, Query, Timeout
+
+__all__ = ["SyncAPIClient"]
+
+DEFAULT_BASE_URL = "https://api.sharetop.top/api"
+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."""
+
+    def __init__(
+        self,
+        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:
+        # Allow None for free tier mode
+        if api_key is None or api_key == "":
+            self.api_key = os.environ.get("SHARETOP_API_KEY")
+        else:
+            self.api_key = api_key
+
+        # Only raise error if we're trying to use the default paid URL without a key
+        if not self.api_key:
+            effective_base_url = base_url or os.environ.get("SHARETOP_BASE_URL")
+            if effective_base_url is None or effective_base_url == DEFAULT_BASE_URL:
+                raise ValueError(
+                    "Token is required for paid API. "
+                    "无效Token，请关注公众号：“浔溯de小仓鼠”进行获取"
+                )
+
+        if self.api_key and len(self.api_key) != 50:
+            raise ValueError(
+                "Invalid API key."
+                "无效Token，请关注公众号：“浔溯de小仓鼠”进行获取"
+            )
+
+        self.base_url = (
+            base_url or os.environ.get("SHARETOP_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]:
+        """Build request headers with authentication."""
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"sharetop-python-sdk/{__version__}",
+            **self._default_headers,
+        }
+        # Only add API key if present (free tier doesn't need it)
+        if self.api_key:
+            headers["Authorization"] = ' '.join(["Bearer", self.api_key])
+        if extra_headers:
+            headers.update(extra_headers)
+        # print("headers:", headers)
+        return headers
+
+    def _build_url(self, path: str) -> str:
+        """Build full URL from path."""
+        return f"{self.base_url}{path}"
+
+    @property
+    def default_headers(self):
+        return self._default_headers
+
+
+class SyncAPIClient(BaseClient):
+    """Synchronous HTTP client for ShareTop API with automatic retry.
+
+    Parameters
+    ----------
+    api_key : str, optional
+        API key for authentication. If not provided, reads from SHARETOP_API_KEY
+        environment variable.
+    base_url : str, optional
+        Base URL for the API. Defaults to https://api.sharetop.com.
+    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.
+    """
+
+    def __init__(
+        self,
+        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, max_retries, default_headers)
+        self._client = httpx.Client(timeout=timeout, verify=False)
+
+    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,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make an HTTP request with automatic retry on failures.
+
+        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.
+        max_retries : int, optional
+            Override max retries for this request.
+
+        Returns
+        -------
+        Any
+            Parsed JSON response.
+
+        Raises
+        ------
+        APIError
+            If the API returns an error response after all retries.
+        ConnectionError
+            If there's a network connection issue after all retries.
+        TimeoutError
+            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}
+
+        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:
+                    # print("url==:", url)
+                    # print("json===========:", json)
+                    response_body = response.json()
+                    # print("response_body==========:", response_body)
+                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,
+        path: str,
+        *,
+        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 with automatic retry."""
+        return self._request(
+            "GET",
+            path,
+            params=params,
+            extra_headers=extra_headers,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    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,
+        max_retries: Union[int, NotGiven] = NOT_GIVEN,
+    ) -> Any:
+        """Make a POST request with automatic retry."""
+        return self._request(
+            "POST",
+            path,
+            json=json,
+            params=params,
+            extra_headers=extra_headers,
+            timeout=timeout,
+            max_retries=max_retries,
+        )

sharetop/_batch.py

@@ -0,0 +1,177 @@
+"""Generic batched GET utilities for splitting large symbol lists across requests.
+
+Handles URL length limits by automatically chunking the symbol list and
+merging ``response["data"]`` dicts from each chunk.  Both synchronous
+(ThreadPoolExecutor) and asynchronous (asyncio.Semaphore) variants are
+provided so that any resource can reuse the same logic.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+from typing import Any, Callable, Dict, List, Optional, Union
+
+
+from ._base_client import SyncAPIClient
+
+DEFAULT_BATCH_SIZE = 100
+DEFAULT_MAX_WORKERS = 5
+
+
+def _chunk_list(lst: List[str], chunk_size: int) -> List[List[str]]:
+    return [lst[i : i + chunk_size] for i in range(0, len(lst), chunk_size)]
+
+
+def _get_progress_bar(total: int, desc: str, show: bool):
+    if show:
+        try:
+            from tqdm.auto import tqdm
+
+            return tqdm(total=total, desc=desc, leave=False)
+        except ImportError:
+            pass
+    return None
+
+
+def _default_merge(
+    acc: Dict[str, Any], chunk: Union[Dict[str, Any], List], symbols: List[str] = None
+) -> None:
+    """Default merge: if chunk is a dict, update directly; if it's a list, group by ts_code."""
+    if isinstance(chunk, dict):
+        acc.update(chunk)
+    elif isinstance(chunk, list) and symbols:
+        # Group list items by ts_code
+        for item in chunk:
+            ts_code = item.get("ts_code", "")
+            if ts_code:
+                # Match with provided symbols
+                for sym in symbols:
+                    # Match by code prefix (e.g., "603435" matches "603435.SH")
+                    code = ts_code.split(".")[0]
+                    sym_code = sym.split(".")[0]
+                    if code == sym_code:
+                        acc.setdefault(sym, []).append(item)
+                        break
+                else:
+                    # No match, put in empty key
+                    acc.setdefault("", []).append(item)
+            else:
+                acc.setdefault("", []).append(item)
+    elif isinstance(chunk, list):
+        acc.setdefault("", []).extend(chunk)
+
+
+def batched_get_sync(
+    client: "SyncAPIClient",
+    endpoint: str,
+    symbols: List[str],
+    params: Dict[str, Any],
+    *,
+    symbols_param: str = "symbols",
+    batch_size: int = DEFAULT_BATCH_SIZE,
+    max_workers: int = DEFAULT_MAX_WORKERS,
+    show_progress: bool = False,
+    progress_desc: str = "Fetching data",
+    merge: Optional[
+        Callable[[Dict[str, Any], Union[Dict[str, Any], List], List[str]], None]
+    ] = None,
+) -> Dict[str, Any]:
+    """Fetch *endpoint* in chunks, merging responses.
+
+    Parameters
+    ----------
+    merge : callable, optional
+        ``merge(accumulated, chunk_data, symbols)`` – custom merge strategy.
+        Defaults to grouping list responses by ts_code.
+    """
+    # If no symbols provided, fetch all data without symbols_param
+    if not symbols:
+        return client.post(endpoint, json=params)["data"]
+
+    chunks = _chunk_list(symbols, batch_size)
+    _merge = merge or _default_merge
+
+    if len(chunks) == 1:
+        chunk_params = {**params, symbols_param: ",".join(chunks[0])}
+        data = client.post(endpoint, json=chunk_params)["data"]
+        # Use merge for single chunk too, to convert list to dict
+        result: Dict[str, Any] = {}
+        _merge(result, data, symbols)
+        return result
+
+    pbar = _get_progress_bar(len(chunks), progress_desc, show_progress)
+    all_data: Dict[str, Any] = {}
+
+    def _fetch(chunk: List[str]) -> Any:
+        chunk_params = {**params, symbols_param: ",".join(chunk)}
+        return client.post(endpoint, json=chunk_params)["data"]
+
+    try:
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as pool:
+            futures = {pool.submit(_fetch, c): c for c in chunks}
+            for future in concurrent.futures.as_completed(futures):
+                _merge(all_data, future.result(), symbols)
+                if pbar:
+                    pbar.update(1)
+    finally:
+        if pbar:
+            pbar.close()
+
+    return all_data
+
+
+# async def batched_get_async(
+#     client: "AsyncAPIClient",
+#     endpoint: str,
+#     symbols: List[str],
+#     params: Dict[str, Any],
+#     *,
+#     symbols_param: str = "symbols",
+#     batch_size: int = DEFAULT_BATCH_SIZE,
+#     max_concurrency: int = DEFAULT_MAX_WORKERS,
+#     show_progress: bool = False,
+#     progress_desc: str = "Fetching data",
+#     merge: Optional[
+#         Callable[[Dict[str, Any], Union[Dict[str, Any], List], List[str]], None]
+#     ] = None,
+# ) -> Dict[str, Any]:
+#     """Async variant of :func:`batched_get_sync`."""
+#     # If no symbols provided, fetch all data without symbols_param
+#     if not symbols:
+#         return (await client.post(endpoint, json=params))["data"]
+#
+#     chunks = _chunk_list(symbols, batch_size)
+#     _merge = merge or _default_merge
+#
+#     if len(chunks) == 1:
+#         chunk_params = {**params, symbols_param: ",".join(chunks[0])}
+#         data = (await client.get(endpoint, params=chunk_params))["data"]
+#         result: Dict[str, Any] = {}
+#         _merge(result, data, symbols)
+#         return result
+#
+#     pbar = _get_progress_bar(len(chunks), progress_desc, show_progress)
+#     sem = asyncio.Semaphore(max_concurrency)
+#     all_data: Dict[str, Any] = {}
+#
+#     async def _fetch(chunk: List[str]) -> Any:
+#         async with sem:
+#             chunk_params = {**params, symbols_param: ",".join(chunk)}
+#             resp = await client.get(endpoint, params=chunk_params)
+#             if pbar:
+#                 pbar.update(1)
+#             return resp["data"]
+#
+#     try:
+#         results = await asyncio.gather(
+#             *[_fetch(c) for c in chunks], return_exceptions=True
+#         )
+#         for r in results:
+#             if isinstance(r, Exception):
+#                 raise r
+#             _merge(all_data, r, symbols)
+#     finally:
+#         if pbar:
+#             pbar.close()
+#
+#     return all_data

sharetop/_cache.py

@@ -0,0 +1,135 @@
+"""Local instrument name cache for ShareTop.
+
+Caches symbol -> name mappings to avoid frequent API calls.
+Cache directory is configurable via SHARETOP_CACHE_DIR environment variable.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from ._base_client import SyncAPIClient
+
+logger = logging.getLogger("sharetop.cache")
+
+DEFAULT_CACHE_DIR = os.path.join(Path.home(), ".sharetop", "cache")
+CACHE_FILENAME = "instruments.json"
+CACHE_TTL_SECONDS = 24 * 60 * 60  # 24 hours
+MAX_BATCH_SIZE = 500
+
+
+def _get_cache_dir() -> str:
+    return os.environ.get("SHARETOP_CACHE_DIR", DEFAULT_CACHE_DIR)
+
+
+class InstrumentNameCache:
+    """Thread-safe local cache for instrument names.
+
+    Backed by an in-memory dict and a JSON file on disk.
+    Resolves missing names from the instruments API on demand.
+    """
+
+    def __init__(self, cache_dir: Optional[str] = None) -> None:
+        self._cache_dir = cache_dir or _get_cache_dir()
+        self._names: Dict[str, str] = {}
+        self._updated_at: float = 0.0
+        self._lock = threading.Lock()
+        self._load_from_disk()
+
+    @property
+    def _cache_path(self) -> str:
+        return os.path.join(self._cache_dir, CACHE_FILENAME)
+
+    # ---- public API ----
+
+    def get_name(self, symbol: str) -> Optional[str]:
+        with self._lock:
+            return self._names.get(symbol)
+
+    def get_names(self, symbols: List[str]) -> Dict[str, str]:
+        with self._lock:
+            return {s: self._names[s] for s in symbols if s in self._names}
+
+    def missing(self, symbols: List[str]) -> List[str]:
+        with self._lock:
+            return [s for s in symbols if s not in self._names]
+
+    def update(self, names: Dict[str, str]) -> None:
+        if not names:
+            return
+        with self._lock:
+            self._names.update(names)
+            self._updated_at = time.time()
+        self._save_to_disk()
+
+    def resolve_sync(
+        self, symbols: List[str], client: "SyncAPIClient"
+    ) -> Dict[str, str]:
+        """Resolve names for symbols, fetching missing ones via sync client."""
+        missing = self.missing(symbols)
+        if missing:
+            self._fetch_sync(missing, client)
+        return self.get_names(symbols)
+
+    # ---- internal: fetch from API ----
+
+    def _fetch_sync(self, symbols: List[str], client: "SyncAPIClient") -> None:
+        try:
+            for i in range(0, len(symbols), MAX_BATCH_SIZE):
+                chunk = symbols[i : i + MAX_BATCH_SIZE]
+                response = client.post("/v1/instruments", json={"symbols": chunk})
+                names = {
+                    inst["symbol"]: inst["name"]
+                    for inst in response.get("data", [])
+                    if inst.get("name")
+                }
+                self.update(names)
+        except Exception as e:
+            logger.debug("Failed to fetch instrument names: %s", e)
+
+    # ---- disk persistence ----
+
+    def _load_from_disk(self) -> None:
+        path = self._cache_path
+        if not os.path.exists(path):
+            return
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+
+            meta = data.get("_meta", {})
+            saved_at = meta.get("updated_at", 0)
+
+            if time.time() - saved_at > CACHE_TTL_SECONDS:
+                logger.debug("Cache expired, ignoring disk cache")
+                return
+
+            names = data.get("data", {})
+            if isinstance(names, dict):
+                with self._lock:
+                    self._names.update(names)
+                    self._updated_at = saved_at
+                logger.debug("Loaded %d instrument names from cache", len(names))
+        except Exception as e:
+            logger.debug("Failed to load cache from %s: %s", path, e)
+
+    def _save_to_disk(self) -> None:
+        path = self._cache_path
+        try:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with self._lock:
+                payload = {
+                    "_meta": {"updated_at": self._updated_at, "version": 1},
+                    "data": dict(self._names),
+                }
+            with open(path, "w", encoding="utf-8") as f:
+                json.dump(payload, f, ensure_ascii=False)
+        except Exception as e:
+            logger.debug("Failed to save cache to %s: %s", path, e)