Metadata-Version: 2.2
Name: qgdata
Version: 0.1.3
Summary: HTTP SDK for querying pipeline data service
Author: Pipeline Team
License: MIT
Keywords: pipeline,sdk,http,data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas<3.0,>=2.0
Requires-Dist: requests<3.0,>=2.31

# qgdata Python SDK

## 定位

`qgdata` 是 `qgdata-http-service` 的 Python 客户端，提供接近 Tushare 的调用体验，返回 `pandas.DataFrame`。

## 安装

```bash
pip install qgdata
```

## 快速开始

```python
import qgdata as qg

qg.set_token("your-token")
pro = qg.pro_api()

df = pro.stock_basic(
    fields="ts_code,name,list_date",
    order_by="list_date",
    sort="desc",
    limit=20,
)
print(df.head())
```

也支持通过环境变量传入 Token（适合回测/自动化场景）：

```python
import os
os.environ['QGDATA_TOKEN'] = 'your-token'

from qgdata import pro_api
pro = pro_api()
df = pro.daily(ts_code='000001.SZ', start_date='20260101', end_date='20260320')
```

Token 优先级：`pro_api(token=)` > `set_token()` > `QGDATA_TOKEN` 环境变量。

详细的用户接口文档见：`docs/SDK_USER_API.md`。
分钟行情专版文档见：`docs/SDK_USER_API_STK_MINS.md`。

## 核心接口

统一查询：

```python
df = pro.query(
    "stock_basic",
    ts_code="000001.SZ",
    fields=["ts_code", "name", "list_date"],
    order_by="list_date",
    sort="desc",
    limit=200,
    offset=0,
)
```

动态方法（等价于 `query`）：

```python
df = pro.stock_basic(ts_code="000001.SZ", limit=50)
```

获取 API 列表：

```python
apis = pro.list_apis(enabled_only=True)
```

## 核心能力

- `set_token()` + `pro_api()` 初始化
- `pro.query(...)` 统一查询
- `pro.xxx(...)` 动态 API 调用
- `pro.list_apis(...)` 拉取可用接口

## 参数约定

- 支持普通参数和列表参数
- 支持分页：`limit` / `offset`
- 支持排序：`order_by` / `sort`（`asc`、`desc`）
- 参数语义由服务端解释

## 异常处理

HTTP 或业务错误会抛出 `PipelineSDKError`：

```python
from qgdata import PipelineSDKError

try:
    df = pro.query("stock_basic", limit=10)
except PipelineSDKError as exc:
    print("message:", exc)
    print("code:", exc.code)
    print("detail:", exc.detail)
```

常见错误消息：

- `unauthorized`（401）
- 其它服务端 `message`（统一透传）

## 开发与发布

```bash
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*
```

更多发布步骤：`docs/PYPI_PUBLISH.md`。
