Metadata-Version: 2.4
Name: mmcqdata
Version: 0.1.0
Summary: Python SDK for querying StarRocks data.
Author: MMCQ
Keywords: data,sdk,sql,starrocks
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: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: pymysql
Provides-Extra: pandas
Requires-Dist: pandas; extra == 'pandas'
Provides-Extra: release
Requires-Dist: build; extra == 'release'
Requires-Dist: twine; extra == 'release'
Description-Content-Type: text/markdown

# mmcqdata

`mmcqdata` 是一个面向 StarRocks 查询场景的轻量 Python SDK，提供连接管理、SQL 查询和可选的 `pandas` 输出能力。

## 安装

安装基础版本：

```bash
pip install mmcqdata
```

如果需要直接返回 `pandas.DataFrame`：

```bash
pip install "mmcqdata[pandas]"
```

## 快速开始

```python
from mmcqdata import StarRocksClient, StarRocksConfig

config = StarRocksConfig(
    host="starrocks.example.com",
    port=9030,
    user="readonly_user",
    password="secret",
    database="analytics",
)

with StarRocksClient(config) as client:
    rows = client.query(
        "SELECT trade_date, symbol, close FROM daily_bar WHERE symbol = %s LIMIT 5",
        ("600519.SH",),
    )
    print(rows)
```

## 环境变量初始化

也可以通过环境变量创建客户端：

```bash
export MMCQDATA_HOST="starrocks.example.com"
export MMCQDATA_PORT="9030"
export MMCQDATA_USER="readonly_user"
export MMCQDATA_PASSWORD="secret"
export MMCQDATA_DATABASE="analytics"
```

```python
from mmcqdata import StarRocksClient

with StarRocksClient.from_env() as client:
    row = client.query_one("SELECT 1 AS ok")
    print(row)
```

默认读取以下环境变量：

- `MMCQDATA_HOST`
- `MMCQDATA_PORT`
- `MMCQDATA_USER`
- `MMCQDATA_PASSWORD`
- `MMCQDATA_DATABASE`
- `MMCQDATA_CONNECT_TIMEOUT`
- `MMCQDATA_READ_TIMEOUT`
- `MMCQDATA_WRITE_TIMEOUT`

## 可用接口

- `StarRocksClient.query()`：返回多行字典结果。
- `StarRocksClient.query_one()`：返回单行字典结果。
- `StarRocksClient.execute()`：执行 SQL 并返回影响行数。
- `StarRocksClient.query_dataframe()`：返回 `pandas.DataFrame`。
- `StarRocksClient.ping()`：检查连接是否可用。

## 发布到 PyPI

仓库里已经提供了发布脚本 `scripts/publish.sh`。该脚本会：

1. 安装发布需要的工具。
2. 构建源码包和 wheel。
3. 执行 `twine check`。
4. 使用环境变量中的 `PYPI_TOKEN` 上传到 PyPI。

使用方式：

```bash
cd /Users/water/Documents/workspace/quant/repos/mmcqdata
export PYPI_TOKEN="pypi-xxxxxxxxxxxxxxxx"
./scripts/publish.sh
```

也可以执行：

```bash
bash scripts/publish.sh
```

不建议使用：

```bash
sh scripts/publish.sh
```

如果只想先试传到 TestPyPI，可以额外设置：

```bash
export PYPI_REPOSITORY_URL="https://test.pypi.org/legacy/"
./scripts/publish.sh
```

注意：不要把真实 token 写进仓库文件，直接放在终端环境变量里即可。
