gangtise-openapi 0.1.0__tar.gz

gangtise_openapi-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+.env.*
+!.env.example
+.DS_Store
+
+.claude/

gangtise_openapi-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-28
+
+### Added
+- Initial release.
+- 73 endpoints from gangtise-openapi-cli v0.14.2.
+- Sync (`gangtise`) and async (`gangtise.async_`) APIs.
+- DataFrame-by-default returns with `raw=True` escape hatch.
+- Auto-pagination concurrency, retry + token self-heal, K-line full-market date sharding, transparent async-content polling.
+- Token cache shared with the npm CLI at `~/.config/gangtise/token.json`.
+- Initial scaffold (pyproject, tooling, CI).

gangtise_openapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gangtiser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gangtise_openapi-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: gangtise-openapi
+Version: 0.1.0
+Summary: Python SDK for Gangtise OpenAPI
+Project-URL: Homepage, https://github.com/gangtiser/gangtise-python
+Project-URL: Source, https://github.com/gangtiser/gangtise-python
+Project-URL: Issues, https://github.com/gangtiser/gangtise-python/issues
+Author: gangtiser
+License: MIT
+License-File: LICENSE
+Keywords: finance,gangtise,openapi,quote,research,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pandas>=2.0
+Description-Content-Type: text/markdown
+
+# gangtise-openapi
+
+Python SDK for [Gangtise OpenAPI](https://open.gangtise.com). Feature-parity with the npm CLI [`gangtise-openapi-cli`](https://github.com/gangtiser/gangtise-openapi-cli) v0.14.2 across 73 endpoints.
+
+## Install
+
+```bash
+pip install gangtise-openapi
+```
+
+Requires Python 3.10+.
+
+## Configure
+
+```bash
+export GANGTISE_ACCESS_KEY=ak_xxx
+export GANGTISE_SECRET_KEY=sk_xxx
+```
+
+(Or pass `access_key=` and `secret_key=` explicitly to `GangtiseClient`.) The token cache file at `~/.config/gangtise/token.json` is shared with the npm CLI.
+
+## Quickstart
+
+```python
+from gangtise_openapi import gangtise
+
+# Tabular endpoints return a pandas DataFrame
+df = gangtise.quote.day_kline(
+    security="000001.SH",
+    start_date="2026-01-01",
+    end_date="2026-01-31",
+)
+
+# Use raw=True to get the underlying dict/list
+result = gangtise.insight.opinion_list(industry=1, size=20, raw=True)
+
+# Async
+import asyncio
+
+async def main():
+    df = await gangtise.async_.quote.day_kline(security="000001.SH")
+
+asyncio.run(main())
+```
+
+## Endpoints
+
+The SDK exposes 73 endpoints across 9 domains:
+
+- `gangtise.auth.*` — login, status
+- `gangtise.lookup.*` — local lookup tables (research areas, brokers, industries, ...)
+- `gangtise.reference.*` — securities search (GTS codes)
+- `gangtise.insight.*` — opinions, research reports, announcements, schedules
+- `gangtise.quote.*` — K-line, real-time quotes
+- `gangtise.fundamental.*` — financial statements, valuation, holders, forecasts
+- `gangtise.ai.*` — AI-generated insights (one-pager, peer comparison, earnings reviews, ...)
+- `gangtise.vault.*` — personal drive, meeting records, stock pools, WeChat
+- `gangtise.alternative.*` — economic indicators (EDB)
+
+See the [npm CLI README](https://github.com/gangtiser/gangtise-openapi-cli#readme) for endpoint-by-endpoint documentation; the Python wrappers accept the same parameters as the CLI flags (snake_case instead of `--kebab-case`).
+
+## License
+
+MIT

gangtise_openapi-0.1.0/README.md

@@ -0,0 +1,64 @@
+# gangtise-openapi
+
+Python SDK for [Gangtise OpenAPI](https://open.gangtise.com). Feature-parity with the npm CLI [`gangtise-openapi-cli`](https://github.com/gangtiser/gangtise-openapi-cli) v0.14.2 across 73 endpoints.
+
+## Install
+
+```bash
+pip install gangtise-openapi
+```
+
+Requires Python 3.10+.
+
+## Configure
+
+```bash
+export GANGTISE_ACCESS_KEY=ak_xxx
+export GANGTISE_SECRET_KEY=sk_xxx
+```
+
+(Or pass `access_key=` and `secret_key=` explicitly to `GangtiseClient`.) The token cache file at `~/.config/gangtise/token.json` is shared with the npm CLI.
+
+## Quickstart
+
+```python
+from gangtise_openapi import gangtise
+
+# Tabular endpoints return a pandas DataFrame
+df = gangtise.quote.day_kline(
+    security="000001.SH",
+    start_date="2026-01-01",
+    end_date="2026-01-31",
+)
+
+# Use raw=True to get the underlying dict/list
+result = gangtise.insight.opinion_list(industry=1, size=20, raw=True)
+
+# Async
+import asyncio
+
+async def main():
+    df = await gangtise.async_.quote.day_kline(security="000001.SH")
+
+asyncio.run(main())
+```
+
+## Endpoints
+
+The SDK exposes 73 endpoints across 9 domains:
+
+- `gangtise.auth.*` — login, status
+- `gangtise.lookup.*` — local lookup tables (research areas, brokers, industries, ...)
+- `gangtise.reference.*` — securities search (GTS codes)
+- `gangtise.insight.*` — opinions, research reports, announcements, schedules
+- `gangtise.quote.*` — K-line, real-time quotes
+- `gangtise.fundamental.*` — financial statements, valuation, holders, forecasts
+- `gangtise.ai.*` — AI-generated insights (one-pager, peer comparison, earnings reviews, ...)
+- `gangtise.vault.*` — personal drive, meeting records, stock pools, WeChat
+- `gangtise.alternative.*` — economic indicators (EDB)
+
+See the [npm CLI README](https://github.com/gangtiser/gangtise-openapi-cli#readme) for endpoint-by-endpoint documentation; the Python wrappers accept the same parameters as the CLI flags (snake_case instead of `--kebab-case`).
+
+## License
+
+MIT

gangtise_openapi-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gangtise-openapi"
+dynamic = ["version"]
+description = "Python SDK for Gangtise OpenAPI"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "gangtiser" }]
+keywords = ["gangtise", "finance", "openapi", "sdk", "quote", "research"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pandas>=2.0",
+    "anyio>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/gangtiser/gangtise-python"
+Source = "https://github.com/gangtiser/gangtise-python"
+Issues = "https://github.com/gangtiser/gangtise-python/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "anyio[trio]>=4.0",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "pandas-stubs",
+]
+
+[tool.hatch.version]
+path = "src/gangtise_openapi/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gangtise_openapi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B008"]
+
+[tool.mypy]
+files = ["src"]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+warn_return_any = true
+ignore_missing_imports = false
+
+[[tool.mypy.overrides]]
+module = ["pandas.*", "respx.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+markers = [
+    "live: hits real Gangtise API (skipped by default; run with `pytest -m live`)",
+]

gangtise_openapi-0.1.0/src/gangtise_openapi/__about__.py

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

gangtise_openapi-0.1.0/src/gangtise_openapi/__init__.py

@@ -0,0 +1,28 @@
+import logging as _logging
+import os as _os
+
+from gangtise_openapi.__about__ import __version__
+from gangtise_openapi._client import AsyncGangtiseClient, GangtiseClient
+from gangtise_openapi._errors import (
+    ApiError,
+    ConfigError,
+    DownloadError,
+    GangtiseError,
+    ValidationError,
+)
+from gangtise_openapi._facade import gangtise
+
+__all__ = [
+    "ApiError",
+    "AsyncGangtiseClient",
+    "ConfigError",
+    "DownloadError",
+    "GangtiseClient",
+    "GangtiseError",
+    "ValidationError",
+    "__version__",
+    "gangtise",
+]
+
+if _os.environ.get("GANGTISE_VERBOSE") in {"1", "true", "True", "yes", "YES"}:
+    _logging.getLogger("gangtise_openapi").setLevel(_logging.DEBUG)

gangtise_openapi-0.1.0/src/gangtise_openapi/_async_content.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any
+
+import anyio
+
+from gangtise_openapi._errors import ApiError
+
+POLL_MAX_ATTEMPTS = 14
+_INITIAL_DELAY_S = 5.0
+_MAX_DELAY_S = 30.0
+_GROWTH = 1.6
+
+CODE_PENDING = "410110"
+CODE_TERMINAL = "410111"
+
+
+def next_delay_seconds(attempt: int) -> float:
+    grown = _INITIAL_DELAY_S * (_GROWTH ** (attempt - 1))
+    return min(_MAX_DELAY_S, float(round(grown)))
+
+
+Fetcher = Callable[[], Any]
+Sleeper = Callable[[float], None]
+
+
+def _classify(error: ApiError) -> str:
+    if error.code == CODE_PENDING:
+        return "pending"
+    if error.code == CODE_TERMINAL:
+        return "terminal"
+    return "other"
+
+
+def poll_content(
+    fetch: Fetcher,
+    *,
+    sleep: Sleeper = time.sleep,
+    max_attempts: int = POLL_MAX_ATTEMPTS,
+) -> Any:
+    last_pending: ApiError | None = None
+    for attempt in range(1, max_attempts + 1):
+        try:
+            result = fetch()
+        except ApiError as error:
+            kind = _classify(error)
+            if kind == "terminal":
+                raise ApiError(
+                    "Content generation failed (terminal). Do not retry.",
+                    code=CODE_TERMINAL,
+                ) from error
+            if kind == "other":
+                raise
+            last_pending = error
+        else:
+            if isinstance(result, dict) and result.get("content") is not None:
+                return result
+        if attempt < max_attempts:
+            sleep(next_delay_seconds(attempt))
+    raise ApiError(
+        f"Content not available after {max_attempts} attempts",
+        code=CODE_PENDING,
+    ) from last_pending
+
+
+AsyncFetcher = Callable[[], Any]
+
+
+async def poll_content_async(
+    fetch: AsyncFetcher,
+    *,
+    max_attempts: int = POLL_MAX_ATTEMPTS,
+) -> Any:
+    last_pending: ApiError | None = None
+    for attempt in range(1, max_attempts + 1):
+        try:
+            result = await fetch()
+        except ApiError as error:
+            kind = _classify(error)
+            if kind == "terminal":
+                raise ApiError(
+                    "Content generation failed (terminal). Do not retry.",
+                    code=CODE_TERMINAL,
+                ) from error
+            if kind == "other":
+                raise
+            last_pending = error
+        else:
+            if isinstance(result, dict) and result.get("content") is not None:
+                return result
+        if attempt < max_attempts:
+            await anyio.sleep(next_delay_seconds(attempt))
+    raise ApiError(
+        f"Content not available after {max_attempts} attempts",
+        code=CODE_PENDING,
+    ) from last_pending

gangtise_openapi-0.1.0/src/gangtise_openapi/_auth.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from gangtise_openapi._errors import ConfigError
+
+
+@dataclass(frozen=True)
+class TokenCache:
+    access_token: str
+    expires_in: int
+    time: int
+    expires_at: int
+    uid: int | None = None
+    user_name: str | None = None
+    tenant_id: int | None = None
+
+
+_BUFFER_SECONDS = 300
+
+
+def normalize_token(token: str) -> str:
+    return token if token.startswith("Bearer ") else f"Bearer {token}"
+
+
+def is_cache_valid(cache: TokenCache | None, buffer_seconds: int = _BUFFER_SECONDS) -> bool:
+    if cache is None or not cache.access_token or not cache.expires_at:
+        return False
+    now = int(time.time())
+    return (cache.expires_at - buffer_seconds) > now
+
+
+def read_token_cache(path: Path) -> TokenCache | None:
+    try:
+        raw = path.read_text(encoding="utf8")
+    except OSError:
+        return None
+    try:
+        data: object = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    access_token = data.get("accessToken")
+    expires_at = data.get("expiresAt")
+    if not isinstance(access_token, str) or not isinstance(expires_at, int):
+        return None
+    expires_in_raw = data.get("expiresIn", 0)
+    time_raw = data.get("time", 0)
+    uid = data.get("uid")
+    user_name = data.get("userName")
+    tenant_id = data.get("tenantId")
+    return TokenCache(
+        access_token=access_token,
+        expires_in=int(expires_in_raw) if isinstance(expires_in_raw, int) else 0,
+        time=int(time_raw) if isinstance(time_raw, int) else 0,
+        expires_at=expires_at,
+        uid=uid if isinstance(uid, int) else None,
+        user_name=user_name if isinstance(user_name, str) else None,
+        tenant_id=tenant_id if isinstance(tenant_id, int) else None,
+    )
+
+
+def write_token_cache(path: Path, cache: TokenCache) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "accessToken": cache.access_token,
+        "expiresIn": cache.expires_in,
+        "time": cache.time,
+        "expiresAt": cache.expires_at,
+        "uid": cache.uid,
+        "userName": cache.user_name,
+        "tenantId": cache.tenant_id,
+    }
+    # Atomic write: temp file + rename to avoid partial reads.
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(payload, indent=2), encoding="utf8")
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)
+
+
+def require_credentials(access_key: str | None, secret_key: str | None) -> tuple[str, str]:
+    if not access_key or not secret_key:
+        raise ConfigError("Missing GANGTISE_ACCESS_KEY or GANGTISE_SECRET_KEY")
+    return access_key, secret_key