mmcqdata 0.1.0__tar.gz

mmcqdata-0.1.0/.gitignore

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

mmcqdata-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+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 写进仓库文件，直接放在终端环境变量里即可。

mmcqdata-0.1.0/README.md

@@ -0,0 +1,115 @@
+# 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 写进仓库文件，直接放在终端环境变量里即可。

mmcqdata-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mmcqdata"
+version = "0.1.0"
+description = "Python SDK for querying StarRocks data."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "MMCQ" }
+]
+dependencies = [
+  "pymysql",
+]
+keywords = ["starrocks", "sql", "sdk", "data"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Database",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+pandas = [
+  "pandas",
+]
+release = [
+  "build",
+  "twine",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mmcqdata"]

mmcqdata-0.1.0/scripts/publish.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+if [ -z "${BASH_VERSION:-}" ]; then
+  exec bash "$0" "$@"
+fi
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+if [[ -z "${PYPI_TOKEN:-}" ]]; then
+  echo "Missing PYPI_TOKEN. Example: export PYPI_TOKEN='pypi-xxxxxxxx'" >&2
+  exit 1
+fi
+
+python3 -m pip install --upgrade build twine
+rm -rf build dist src/mmcqdata.egg-info
+python3 -m build
+python3 -m twine check dist/*
+
+if [[ -n "${PYPI_REPOSITORY_URL:-}" ]]; then
+  TWINE_USERNAME="__token__" \
+  TWINE_PASSWORD="$PYPI_TOKEN" \
+  python3 -m twine upload --repository-url "$PYPI_REPOSITORY_URL" dist/*
+else
+  TWINE_USERNAME="__token__" \
+  TWINE_PASSWORD="$PYPI_TOKEN" \
+  python3 -m twine upload dist/*
+fi

mmcqdata-0.1.0/src/mmcqdata/__init__.py

@@ -0,0 +1,13 @@
+from .client import StarRocksClient
+from .config import StarRocksConfig
+from .exceptions import ConfigurationError, MMCQDataError, QueryError
+
+__all__ = [
+    "ConfigurationError",
+    "MMCQDataError",
+    "QueryError",
+    "StarRocksClient",
+    "StarRocksConfig",
+]
+
+__version__ = "0.1.0"

mmcqdata-0.1.0/src/mmcqdata/client.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from contextlib import contextmanager
+from typing import Any, Iterator, TypeAlias
+
+import pymysql
+from pymysql.cursors import DictCursor
+
+from .config import StarRocksConfig
+from .exceptions import QueryError
+
+QueryParams: TypeAlias = Sequence[Any] | Mapping[str, Any]
+
+
+class StarRocksClient:
+    def __init__(self, config: StarRocksConfig, *, connect: bool = True) -> None:
+        self.config = config
+        self._connection: pymysql.connections.Connection | None = None
+
+        if connect:
+            self.open()
+
+    @classmethod
+    def from_env(
+        cls,
+        prefix: str = "MMCQDATA_",
+        *,
+        connect: bool = True,
+    ) -> "StarRocksClient":
+        return cls(StarRocksConfig.from_env(prefix=prefix), connect=connect)
+
+    def open(self) -> None:
+        if self._connection is not None and self._connection.open:
+            return
+
+        try:
+            self._connection = pymysql.connect(
+                **self.config.to_pymysql_kwargs(),
+                cursorclass=DictCursor,
+            )
+        except pymysql.MySQLError as exc:
+            raise QueryError("Failed to connect to StarRocks.") from exc
+
+    def close(self) -> None:
+        if self._connection is not None:
+            self._connection.close()
+            self._connection = None
+
+    def ping(self, reconnect: bool = True) -> None:
+        if self._connection is None:
+            self.open()
+
+        if self._connection is None:
+            raise QueryError("Connection was not initialized.")
+
+        try:
+            self._connection.ping(reconnect=reconnect)
+        except pymysql.MySQLError as exc:
+            raise QueryError("Failed to ping StarRocks.") from exc
+
+    @contextmanager
+    def cursor(self) -> Iterator[Any]:
+        if self._connection is None or not self._connection.open:
+            self.open()
+
+        if self._connection is None:
+            raise QueryError("Connection was not initialized.")
+
+        cursor = self._connection.cursor()
+        try:
+            yield cursor
+        except pymysql.MySQLError as exc:
+            raise QueryError("SQL execution failed.") from exc
+        finally:
+            cursor.close()
+
+    def query(
+        self,
+        sql: str,
+        params: QueryParams | None = None,
+    ) -> list[dict[str, Any]]:
+        with self.cursor() as cursor:
+            cursor.execute(sql, params)
+            rows = cursor.fetchall()
+
+        return [dict(row) for row in rows]
+
+    def query_one(
+        self,
+        sql: str,
+        params: QueryParams | None = None,
+    ) -> dict[str, Any] | None:
+        with self.cursor() as cursor:
+            cursor.execute(sql, params)
+            row = cursor.fetchone()
+
+        return dict(row) if row is not None else None
+
+    def execute(
+        self,
+        sql: str,
+        params: QueryParams | None = None,
+    ) -> int:
+        with self.cursor() as cursor:
+            affected_rows = cursor.execute(sql, params)
+
+        return int(affected_rows)
+
+    def query_dataframe(
+        self,
+        sql: str,
+        params: QueryParams | None = None,
+    ) -> Any:
+        try:
+            import pandas as pd
+        except ImportError as exc:
+            raise QueryError(
+                "pandas is not installed. Please run: pip install 'mmcqdata[pandas]'"
+            ) from exc
+
+        return pd.DataFrame(self.query(sql, params))
+
+    def __enter__(self) -> "StarRocksClient":
+        self.open()
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()

mmcqdata-0.1.0/src/mmcqdata/config.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from typing import Any
+
+from .exceptions import ConfigurationError
+
+
+def _parse_optional_int(value: str | None, *, field_name: str) -> int | None:
+    if value in (None, ""):
+        return None
+
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise ConfigurationError(f"{field_name} must be an integer.") from exc
+
+
+@dataclass(slots=True)
+class StarRocksConfig:
+    host: str
+    user: str
+    password: str = ""
+    port: int = 9030
+    database: str | None = None
+    charset: str = "utf8mb4"
+    connect_timeout: int = 10
+    read_timeout: int | None = None
+    write_timeout: int | None = None
+    autocommit: bool = True
+
+    @classmethod
+    def from_env(cls, prefix: str = "MMCQDATA_") -> "StarRocksConfig":
+        host = os.getenv(f"{prefix}HOST")
+        user = os.getenv(f"{prefix}USER")
+
+        if not host:
+            raise ConfigurationError(f"Missing environment variable: {prefix}HOST")
+        if not user:
+            raise ConfigurationError(f"Missing environment variable: {prefix}USER")
+
+        port_text = os.getenv(f"{prefix}PORT", "9030")
+        connect_timeout_text = os.getenv(f"{prefix}CONNECT_TIMEOUT", "10")
+
+        try:
+            port = int(port_text)
+        except ValueError as exc:
+            raise ConfigurationError(f"{prefix}PORT must be an integer.") from exc
+
+        try:
+            connect_timeout = int(connect_timeout_text)
+        except ValueError as exc:
+            raise ConfigurationError(
+                f"{prefix}CONNECT_TIMEOUT must be an integer."
+            ) from exc
+
+        return cls(
+            host=host,
+            port=port,
+            user=user,
+            password=os.getenv(f"{prefix}PASSWORD", ""),
+            database=os.getenv(f"{prefix}DATABASE") or None,
+            connect_timeout=connect_timeout,
+            read_timeout=_parse_optional_int(
+                os.getenv(f"{prefix}READ_TIMEOUT"),
+                field_name=f"{prefix}READ_TIMEOUT",
+            ),
+            write_timeout=_parse_optional_int(
+                os.getenv(f"{prefix}WRITE_TIMEOUT"),
+                field_name=f"{prefix}WRITE_TIMEOUT",
+            ),
+        )
+
+    def to_pymysql_kwargs(self) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {
+            "host": self.host,
+            "port": self.port,
+            "user": self.user,
+            "password": self.password,
+            "charset": self.charset,
+            "connect_timeout": self.connect_timeout,
+            "autocommit": self.autocommit,
+        }
+
+        if self.database:
+            kwargs["database"] = self.database
+        if self.read_timeout is not None:
+            kwargs["read_timeout"] = self.read_timeout
+        if self.write_timeout is not None:
+            kwargs["write_timeout"] = self.write_timeout
+
+        return kwargs

mmcqdata-0.1.0/src/mmcqdata/exceptions.py

@@ -0,0 +1,10 @@
+class MMCQDataError(Exception):
+    """Base exception for the mmcqdata package."""
+
+
+class ConfigurationError(MMCQDataError):
+    """Raised when the client configuration is invalid."""
+
+
+class QueryError(MMCQDataError):
+    """Raised when StarRocks query execution fails."""