infoway-sdk 0.1.0__tar.gz

infoway_sdk-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.env
+*.log
+.venv/
+.pytest_cache/

infoway_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: infoway-sdk
+Version: 0.1.0
+Summary: Official Python SDK for Infoway real-time financial data API
+Project-URL: Homepage, https://infoway.io
+Project-URL: Documentation, https://docs.infoway.io
+Project-URL: Repository, https://github.com/infoway-io/infoway-sdk-python
+Author-email: Infoway <dev@infoway.io>
+License-Expression: MIT
+Keywords: crypto,finance,forex,market-data,real-time,stock,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Infoway SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/infoway-sdk.svg)](https://pypi.org/project/infoway-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/infoway-sdk.svg)](https://pypi.org/project/infoway-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**English** | [中文](README_CN.md)
+
+Official Python SDK for [Infoway](https://infoway.io) real-time financial data API. Full documentation at [docs.infoway.io](https://docs.infoway.io).
+
+## Installation
+
+```bash
+pip install infoway-sdk
+```
+
+## Quick Start
+
+```python
+from infoway import InfowayClient, KlineType
+
+client = InfowayClient(api_key="YOUR_API_KEY")
+
+# Real-time trades
+trades = client.stock.get_trade("AAPL.US")
+
+# Daily K-lines for crypto
+klines = client.crypto.get_kline("BTCUSDT", kline_type=KlineType.DAY, count=30)
+
+# Market temperature
+temp = client.market.get_temperature(market="HK,US")
+
+# Sector/plate rankings
+plates = client.plate.get_industry("HK", limit=10)
+```
+
+## WebSocket Streaming
+
+```python
+import asyncio
+from infoway.ws import InfowayWebSocket
+
+async def main():
+    ws = InfowayWebSocket(api_key="YOUR_API_KEY", business="stock")
+
+    async def on_trade(msg):
+        print(f"Trade: {msg}")
+
+    ws.on_trade = on_trade
+    await ws.subscribe_trade("AAPL.US,TSLA.US")
+    await ws.connect()
+
+asyncio.run(main())
+```
+
+### WebSocket Features
+
+- **Auto-reconnect** with exponential backoff (1s to 30s cap)
+- **Heartbeat keepalive** at 30-second intervals
+- **Auto-resubscribe** on reconnect -- no manual re-subscription needed
+- Event callbacks: `on_trade`, `on_depth`, `on_kline`, `on_error`, `on_reconnect`, `on_disconnect`
+
+## REST API Modules
+
+| Module | Accessor | Description |
+|--------|----------|-------------|
+| Stock | `client.stock` | HK, US, CN equities -- trade, depth, K-line |
+| Crypto | `client.crypto` | Cryptocurrency pairs -- trade, depth, K-line |
+| Japan | `client.japan` | Japan market data -- trade, depth, K-line |
+| India | `client.india` | India market data -- trade, depth, K-line |
+| Common | `client.common` | Cross-market data -- trade, depth, K-line |
+| Basic | `client.basic` | Symbol lists, trading days, trading hours, adjustment factors |
+| Market | `client.market` | Market temperature, breadth, indexes, leaders, rank config |
+| Plate | `client.plate` | Sector/industry/concept plates, members, charts |
+| Stock Info | `client.stock_info` | Fundamentals -- valuation, ratings, company, panorama, events |
+
+## Configuration
+
+You can pass `api_key` directly or set it via environment variable:
+
+```bash
+export INFOWAY_API_KEY="YOUR_API_KEY"
+```
+
+```python
+# Reads INFOWAY_API_KEY from environment automatically
+client = InfowayClient()
+```
+
+### Client Options
+
+```python
+client = InfowayClient(
+    api_key="YOUR_API_KEY",
+    base_url="https://data.infoway.io",  # default
+    timeout=15.0,                         # request timeout in seconds
+    max_retries=3,                        # retry count for failed requests
+)
+```
+
+## Error Handling
+
+```python
+from infoway import InfowayClient, InfowayAPIError, InfowayAuthError, InfowayTimeoutError
+
+client = InfowayClient(api_key="YOUR_API_KEY")
+
+try:
+    trades = client.stock.get_trade("AAPL.US")
+except InfowayAuthError:
+    print("Invalid API key")
+except InfowayTimeoutError:
+    print("Request timed out")
+except InfowayAPIError as e:
+    print(f"API error [{e.ret}]: {e.msg}")
+```
+
+## License
+
+MIT
+
+---
+
+Get your free API key at [infoway.io](https://infoway.io) -- 7-day free trial, no credit card required.
+

infoway_sdk-0.1.0/README.md

@@ -0,0 +1,125 @@
+# Infoway SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/infoway-sdk.svg)](https://pypi.org/project/infoway-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/infoway-sdk.svg)](https://pypi.org/project/infoway-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**English** | [中文](README_CN.md)
+
+Official Python SDK for [Infoway](https://infoway.io) real-time financial data API. Full documentation at [docs.infoway.io](https://docs.infoway.io).
+
+## Installation
+
+```bash
+pip install infoway-sdk
+```
+
+## Quick Start
+
+```python
+from infoway import InfowayClient, KlineType
+
+client = InfowayClient(api_key="YOUR_API_KEY")
+
+# Real-time trades
+trades = client.stock.get_trade("AAPL.US")
+
+# Daily K-lines for crypto
+klines = client.crypto.get_kline("BTCUSDT", kline_type=KlineType.DAY, count=30)
+
+# Market temperature
+temp = client.market.get_temperature(market="HK,US")
+
+# Sector/plate rankings
+plates = client.plate.get_industry("HK", limit=10)
+```
+
+## WebSocket Streaming
+
+```python
+import asyncio
+from infoway.ws import InfowayWebSocket
+
+async def main():
+    ws = InfowayWebSocket(api_key="YOUR_API_KEY", business="stock")
+
+    async def on_trade(msg):
+        print(f"Trade: {msg}")
+
+    ws.on_trade = on_trade
+    await ws.subscribe_trade("AAPL.US,TSLA.US")
+    await ws.connect()
+
+asyncio.run(main())
+```
+
+### WebSocket Features
+
+- **Auto-reconnect** with exponential backoff (1s to 30s cap)
+- **Heartbeat keepalive** at 30-second intervals
+- **Auto-resubscribe** on reconnect -- no manual re-subscription needed
+- Event callbacks: `on_trade`, `on_depth`, `on_kline`, `on_error`, `on_reconnect`, `on_disconnect`
+
+## REST API Modules
+
+| Module | Accessor | Description |
+|--------|----------|-------------|
+| Stock | `client.stock` | HK, US, CN equities -- trade, depth, K-line |
+| Crypto | `client.crypto` | Cryptocurrency pairs -- trade, depth, K-line |
+| Japan | `client.japan` | Japan market data -- trade, depth, K-line |
+| India | `client.india` | India market data -- trade, depth, K-line |
+| Common | `client.common` | Cross-market data -- trade, depth, K-line |
+| Basic | `client.basic` | Symbol lists, trading days, trading hours, adjustment factors |
+| Market | `client.market` | Market temperature, breadth, indexes, leaders, rank config |
+| Plate | `client.plate` | Sector/industry/concept plates, members, charts |
+| Stock Info | `client.stock_info` | Fundamentals -- valuation, ratings, company, panorama, events |
+
+## Configuration
+
+You can pass `api_key` directly or set it via environment variable:
+
+```bash
+export INFOWAY_API_KEY="YOUR_API_KEY"
+```
+
+```python
+# Reads INFOWAY_API_KEY from environment automatically
+client = InfowayClient()
+```
+
+### Client Options
+
+```python
+client = InfowayClient(
+    api_key="YOUR_API_KEY",
+    base_url="https://data.infoway.io",  # default
+    timeout=15.0,                         # request timeout in seconds
+    max_retries=3,                        # retry count for failed requests
+)
+```
+
+## Error Handling
+
+```python
+from infoway import InfowayClient, InfowayAPIError, InfowayAuthError, InfowayTimeoutError
+
+client = InfowayClient(api_key="YOUR_API_KEY")
+
+try:
+    trades = client.stock.get_trade("AAPL.US")
+except InfowayAuthError:
+    print("Invalid API key")
+except InfowayTimeoutError:
+    print("Request timed out")
+except InfowayAPIError as e:
+    print(f"API error [{e.ret}]: {e.msg}")
+```
+
+## License
+
+MIT
+
+---
+
+Get your free API key at [infoway.io](https://infoway.io) -- 7-day free trial, no credit card required.
+

infoway_sdk-0.1.0/README_CN.md

@@ -0,0 +1,122 @@
+# Infoway SDK (中文)
+
+[![PyPI version](https://img.shields.io/pypi/v/infoway-sdk.svg)](https://pypi.org/project/infoway-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/infoway-sdk.svg)](https://pypi.org/project/infoway-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English](README.md) | **中文**
+
+[Infoway](https://infoway.io) 实时金融数据 API 的官方 Python SDK。完整文档请访问 [docs.infoway.io](https://docs.infoway.io)。
+
+## 安装
+
+```bash
+pip install infoway-sdk
+```
+
+## 快速开始
+
+```python
+from infoway import InfowayClient, KlineType
+
+client = InfowayClient(api_key="YOUR_API_KEY")
+
+# 实时成交数据
+trades = client.stock.get_trade("AAPL.US")
+
+# 加密货币日K线
+klines = client.crypto.get_kline("BTCUSDT", kline_type=KlineType.DAY, count=30)
+
+# 市场温度
+temp = client.market.get_temperature(market="HK,US")
+
+# 板块排行
+plates = client.plate.get_industry("HK", limit=10)
+```
+
+## WebSocket 实时推送
+
+```python
+import asyncio
+from infoway.ws import InfowayWebSocket
+
+async def main():
+    ws = InfowayWebSocket(api_key="YOUR_API_KEY", business="stock")
+
+    async def on_trade(msg):
+        print(f"成交: {msg}")
+
+    ws.on_trade = on_trade
+    await ws.subscribe_trade("AAPL.US,TSLA.US")
+    await ws.connect()
+
+asyncio.run(main())
+```
+
+### 特性
+
+- **自动重连** -- 指数退避策略（1秒至30秒上限）
+- **心跳保活** -- 每30秒自动发送心跳
+- **自动重新订阅** -- 重连后自动恢复所有订阅，无需手动处理
+- 事件回调：`on_trade`、`on_depth`、`on_kline`、`on_error`、`on_reconnect`、`on_disconnect`
+
+## REST API 模块
+
+| 模块 | 访问方式 | 说明 |
+|------|----------|------|
+| Stock | `client.stock` | 港股、美股、A股 -- 成交、深度、K线 |
+| Crypto | `client.crypto` | 加密货币 -- 成交、深度、K线 |
+| Japan | `client.japan` | 日本市场 -- 成交、深度、K线 |
+| India | `client.india` | 印度市场 -- 成交、深度、K线 |
+| Common | `client.common` | 跨市场数据 -- 成交、深度、K线 |
+| Basic | `client.basic` | 标的列表、交易日、交易时间、复权因子 |
+| Market | `client.market` | 市场温度、市场宽度、指数、龙头股、排行配置 |
+| Plate | `client.plate` | 行业/概念板块、成分股、板块图表 |
+| Stock Info | `client.stock_info` | 基本面 -- 估值、评级、公司概况、全景、事件 |
+
+## 环境变量
+
+```bash
+export INFOWAY_API_KEY="YOUR_API_KEY"
+```
+
+```python
+# 自动从环境变量读取 INFOWAY_API_KEY
+client = InfowayClient()
+```
+
+### 客户端配置
+
+```python
+client = InfowayClient(
+    api_key="YOUR_API_KEY",
+    base_url="https://data.infoway.io",  # 默认值
+    timeout=15.0,                         # 请求超时（秒）
+    max_retries=3,                        # 失败重试次数
+)
+```
+
+## 错误处理
+
+```python
+from infoway import InfowayClient, InfowayAPIError, InfowayAuthError, InfowayTimeoutError
+
+client = InfowayClient(api_key="YOUR_API_KEY")
+
+try:
+    trades = client.stock.get_trade("AAPL.US")
+except InfowayAuthError:
+    print("API Key 无效")
+except InfowayTimeoutError:
+    print("请求超时")
+except InfowayAPIError as e:
+    print(f"API 错误 [{e.ret}]: {e.msg}")
+```
+
+## 许可证
+
+MIT
+
+---
+
+在 [infoway.io](https://infoway.io) 获取免费 API Key -- 7天免费试用，无需信用卡。

infoway_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "infoway-sdk"
+dynamic = ["version"]
+description = "Official Python SDK for Infoway real-time financial data API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Infoway", email = "dev@infoway.io" }]
+keywords = ["finance", "stock", "crypto", "forex", "market-data", "websocket", "real-time"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "httpx>=0.27",
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://infoway.io"
+Documentation = "https://docs.infoway.io"
+Repository = "https://github.com/infoway-io/infoway-sdk-python"
+
+[tool.hatch.version]
+path = "src/infoway/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/infoway"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

infoway_sdk-0.1.0/src/infoway/__init__.py

@@ -0,0 +1,17 @@
+"""Infoway SDK — Official Python client for Infoway real-time financial data API."""
+
+from infoway._version import __version__
+from infoway.client import InfowayClient
+from infoway.exceptions import InfowayAPIError, InfowayAuthError, InfowayTimeoutError
+from infoway._types import KlineType, Business, WsCode
+
+__all__ = [
+    "__version__",
+    "InfowayClient",
+    "InfowayAPIError",
+    "InfowayAuthError",
+    "InfowayTimeoutError",
+    "KlineType",
+    "Business",
+    "WsCode",
+]

infoway_sdk-0.1.0/src/infoway/_http.py

@@ -0,0 +1,84 @@
+"""Low-level HTTP client with retry and error handling."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any
+
+import httpx
+
+from infoway.exceptions import InfowayAPIError, InfowayAuthError, InfowayTimeoutError
+
+logger = logging.getLogger("infoway")
+
+_DEFAULT_BASE_URL = "https://data.infoway.io"
+_DEFAULT_TIMEOUT = 15.0
+_DEFAULT_RETRIES = 3
+
+
+class HttpClient:
+    """HTTP client wrapping httpx with auth, retry, and Infoway error handling."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_RETRIES,
+    ):
+        self._api_key = api_key or os.getenv("INFOWAY_API_KEY", "")
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={"apiKey": self._api_key},
+            timeout=self._timeout,
+        )
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        return self._request("POST", path, json=json)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries):
+            try:
+                resp = self._client.request(method, path, **kwargs)
+                return self._handle_response(resp)
+            except (InfowayAPIError, InfowayAuthError):
+                raise
+            except httpx.TimeoutException as e:
+                last_exc = InfowayTimeoutError(str(e))
+            except httpx.HTTPError as e:
+                last_exc = e
+                logger.debug("Request failed (attempt %d/%d): %s", attempt + 1, self._max_retries, e)
+            if attempt < self._max_retries - 1:
+                time.sleep(min(2 ** attempt, 8))
+        raise last_exc
+
+    def _handle_response(self, resp: httpx.Response) -> Any:
+        if resp.status_code == 401:
+            raise InfowayAuthError()
+        data = resp.json()
+        ret = data.get("ret") or data.get("code", 200)
+        msg = data.get("msg", "")
+        trace_id = data.get("traceId")
+        if ret == 401:
+            raise InfowayAuthError(msg)
+        if ret != 200:
+            raise InfowayAPIError(ret=ret, msg=msg, trace_id=trace_id)
+        return data.get("data")
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args: Any):
+        self.close()

infoway_sdk-0.1.0/src/infoway/_types.py

@@ -0,0 +1,39 @@
+"""Shared type definitions and enums."""
+
+from enum import IntEnum
+
+
+class KlineType(IntEnum):
+    MIN_1 = 1
+    MIN_5 = 2
+    MIN_15 = 3
+    MIN_30 = 4
+    HOUR_1 = 5
+    HOUR_2 = 6
+    HOUR_4 = 7
+    DAY = 8
+    WEEK = 9
+    MONTH = 10
+    QUARTER = 11
+    YEAR = 12
+
+
+class Business(str):
+    STOCK = "stock"
+    JAPAN = "japan"
+    INDIA = "india"
+    CRYPTO = "crypto"
+    COMMON = "common"
+
+
+class WsCode(IntEnum):
+    SUB_TRADE = 10000
+    PUSH_TRADE = 10001
+    UNSUB_TRADE = 10002
+    SUB_DEPTH = 10003
+    PUSH_DEPTH = 10004
+    UNSUB_DEPTH = 10005
+    SUB_KLINE = 10006
+    PUSH_KLINE = 10007
+    UNSUB_KLINE = 10008
+    HEARTBEAT = 10010

infoway_sdk-0.1.0/src/infoway/_version.py

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

infoway_sdk-0.1.0/src/infoway/client.py

@@ -0,0 +1,57 @@
+"""Main entry point for the Infoway SDK."""
+
+from __future__ import annotations
+
+from infoway._http import HttpClient
+from infoway.rest.stock import StockClient
+from infoway.rest.crypto import CryptoClient
+from infoway.rest.japan import JapanClient
+from infoway.rest.india import IndiaClient
+from infoway.rest.common import CommonClient
+from infoway.rest.basic import BasicClient
+from infoway.rest.market import MarketClient
+from infoway.rest.plate import PlateClient
+from infoway.rest.stock_info import StockInfoClient
+
+
+class InfowayClient:
+    """Infoway API client.
+
+    Usage::
+
+        from infoway import InfowayClient
+
+        client = InfowayClient(api_key="YOUR_API_KEY")
+        trades = client.stock.get_trade("AAPL.US")
+        klines = client.crypto.get_kline("BTCUSDT", kline_type=8, count=100)
+        temp = client.market.get_temperature(market="HK,US")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://data.infoway.io",
+        timeout: float = 15.0,
+        max_retries: int = 3,
+    ):
+        self._http = HttpClient(
+            api_key=api_key, base_url=base_url, timeout=timeout, max_retries=max_retries,
+        )
+        self.stock = StockClient(self._http)
+        self.crypto = CryptoClient(self._http)
+        self.japan = JapanClient(self._http)
+        self.india = IndiaClient(self._http)
+        self.common = CommonClient(self._http)
+        self.basic = BasicClient(self._http)
+        self.market = MarketClient(self._http)
+        self.plate = PlateClient(self._http)
+        self.stock_info = StockInfoClient(self._http)
+
+    def close(self):
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

infoway_sdk-0.1.0/src/infoway/exceptions.py

@@ -0,0 +1,22 @@
+"""Infoway SDK exception types."""
+
+
+class InfowayTimeoutError(Exception):
+    """Raised when a request times out."""
+
+
+class InfowayAPIError(Exception):
+    """Raised when the API returns a non-success response."""
+
+    def __init__(self, ret: int, msg: str, trace_id: str | None = None):
+        self.ret = ret
+        self.msg = msg
+        self.trace_id = trace_id
+        super().__init__(f"[{ret}] {msg}" + (f" (trace: {trace_id})" if trace_id else ""))
+
+
+class InfowayAuthError(InfowayAPIError):
+    """Raised on 401 Unauthorized."""
+
+    def __init__(self, msg: str = "Unauthorized"):
+        super().__init__(ret=401, msg=msg)