semvec/pypi-packages huggingface dataset:
qgdata 0.1.1
HTTP SDK for querying pipeline data service
License: MIT
Requires Python: >=3.10
Keywords: pipeline, sdk, http, data

# 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())
```

详细的用户接口文档见：`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`。