qqflow-sdk 0.9.0__tar.gz

qqflow_sdk-0.9.0/.gitignore

@@ -0,0 +1,33 @@
+# 本目录自己的忽略规则。放这份文件有两个必须一起成立的理由：
+#
+# 1) cargo：仓库根那条 /dist 只锚定仓库根，管不到 clients/python/dist，而
+#    python -m build 的产物正好落在那里。cargo 收的是「git 跟踪的文件 ＋ 未跟踪但
+#    也没被 ignore 的文件」，所以预演一跑就会把 wheel/sdist 静默带进根 crate。
+# 2) hatchling：它只读「项目根向上第一个 .gitignore」，命中即停、不与父级的合并。
+#    放了这份，仓库根那几十行对 hatchling 就整体失效——所以**密钥与临时物的兜底必须
+#    在这里重复一遍**，否则有人把 keys.json 拷进 clients/python，它就会被打进 sdist。
+#    （真正挡住 .venv 的一直是 hatchling 的硬编码目录集，不是仓库根那条带路径前缀、
+#    相对本项目匹配不上的规则；这里用无前缀写法，换后端也不裸奔。）
+#
+# 改完这份文件务必复跑：
+#   git ls-files clients/python | git check-ignore -v --no-index --stdin
+# 输出必须为空——否则说明某条规则把**已跟踪**文件也吞了，它会静默从包里消失。
+.venv/
+dist/
+__pycache__/
+*.py[cod]
+
+# 密钥与本地配置（与仓库根同源，为 hatchling 重复一次）
+keys.json
+all_keys.json
+*-server.json
+.env
+*.local
+
+# 临时物与噪声
+*.log
+*.bak
+*.json.tmp
+.DS_Store
+Thumbs.db
+Desktop.ini

qqflow_sdk-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ren-yc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qqflow_sdk-0.9.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: qqflow-sdk
+Version: 0.9.0
+Summary: Typed Python client for qqflow-server's HTTP API (generated models + handwritten behavior layer)
+Project-URL: Homepage, https://github.com/ren-yc/qqflow-server
+Project-URL: Repository, https://github.com/ren-yc/qqflow-server
+Project-URL: Issues, https://github.com/ren-yc/qqflow-server/issues
+Author: ren-yc
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: typing-extensions>=4.7
+Provides-Extra: dev
+Requires-Dist: openapi-generator-cli>=7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.16.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qqflow-sdk
+
+Typed Python client for [qqflow-server](https://github.com/ren-yc/qqflow-server) — a headless, read-only HTTP/SSE service over local QQ NT chat databases.
+
+Generated from the server's OpenAPI description (types + request plumbing), with a handwritten behavior layer on top: transport failures folded into a proper error tree, readiness polling, pagination helpers, SSE streaming, and media download helpers.
+
+## Install
+
+```
+pip install qqflow-sdk
+```
+
+## Minimal example
+
+```python
+import asyncio
+
+from qqflow_sdk import Client
+
+
+async def main() -> None:
+    client = Client(base_url="http://127.0.0.1:5032", token="your-token")
+    await client.health()
+    sessions = await client.list_all_sessions()
+    await client.aclose()
+
+
+asyncio.run(main())
+```
+
+## Scope
+
+The server exposes a strictly read-only surface: accounts, sessions, messages, contacts, group members, media export, and an SSE push stream. This client mirrors that surface one-to-one; see the server repository for the API reference and the interface contract the client is tested against.
+
+## License
+
+MIT

qqflow_sdk-0.9.0/README.md

@@ -0,0 +1,37 @@
+# qqflow-sdk
+
+Typed Python client for [qqflow-server](https://github.com/ren-yc/qqflow-server) — a headless, read-only HTTP/SSE service over local QQ NT chat databases.
+
+Generated from the server's OpenAPI description (types + request plumbing), with a handwritten behavior layer on top: transport failures folded into a proper error tree, readiness polling, pagination helpers, SSE streaming, and media download helpers.
+
+## Install
+
+```
+pip install qqflow-sdk
+```
+
+## Minimal example
+
+```python
+import asyncio
+
+from qqflow_sdk import Client
+
+
+async def main() -> None:
+    client = Client(base_url="http://127.0.0.1:5032", token="your-token")
+    await client.health()
+    sessions = await client.list_all_sessions()
+    await client.aclose()
+
+
+asyncio.run(main())
+```
+
+## Scope
+
+The server exposes a strictly read-only surface: accounts, sessions, messages, contacts, group members, media export, and an SSE push stream. This client mirrors that surface one-to-one; see the server repository for the API reference and the interface contract the client is tested against.
+
+## License
+
+MIT

qqflow_sdk-0.9.0/openapitools.json

@@ -0,0 +1,5 @@
+{
+  "generator-cli": {
+    "version": "7.25.0"
+  }
+}

qqflow_sdk-0.9.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qqflow-sdk"
+version = "0.9.0"
+description = "Typed Python client for qqflow-server's HTTP API (generated models + handwritten behavior layer)"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [{ name = "ren-yc" }]
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.7",
+  "python-dateutil>=2.8",
+  "typing-extensions>=4.7",
+]
+
+[project.optional-dependencies]
+# ruff is pinned exactly: the lint gate below selects rules explicitly,
+# but rule *behavior* still drifts with the ruff version - an unpinned
+# CI step could go red (or silently green) on a day nobody changed code.
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "openapi-generator-cli>=7", "ruff==0.16.1"]
+
+[project.urls]
+Homepage = "https://github.com/ren-yc/qqflow-server"
+Repository = "https://github.com/ren-yc/qqflow-server"
+Issues = "https://github.com/ren-yc/qqflow-server/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qqflow_sdk"]
+
+# Explicit lint config: relying on ruff defaults would tie CI to whatever
+# a version bump decides the default set is. The generated tree is
+# excluded *here only* - CLI --extend-exclude resolves relative to the
+# cwd (from repo root that spelling silently scans the whole generated
+# tree), and passing --config shifts config-relative excludes to cwd too.
+# Keeping the exclude in this file makes it config-dir-relative, which is
+# the one form that works from both clients/python and the repo root.
+[tool.ruff]
+extend-exclude = ["src/qqflow_sdk/generated"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "RUF", "G", "LOG", "BLE", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

qqflow_sdk-0.9.0/scripts/regen.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""Regenerate clients/python/src/qqflow_sdk/generated from the server's
+OpenAPI description.
+
+Source of truth is the committed golden snapshot's body (the same bytes the
+server served when the snapshot was pinned), normalized to OpenAPI 3.0 the
+same way the Rust regen tool does it:
+
+  1. placeholder-masked volatile values (the golden masks a few string
+     properties) are restored to plain string schemas;
+  2. `type: [T, null]` becomes `T` + `nullable: true` (3.1 -> 3.0);
+  3. `oneOf: [T, {type: null}]` - utoipa's spelling of `Option<T>` - keeps
+     only the non-null arm (the handlers omit the key entirely when absent);
+  4. path-template placeholders get matching `parameters` declarations (the
+     server emits them since the same batch; kept here so regeneration also
+     works from a description fetched over HTTP).
+
+The normalized spec is committed next to the generated client, and CI
+asserts that rerunning this script produces no diff. Edit nothing under
+generated/ by hand.
+
+Usage:
+    python scripts/regen.py            # regenerate (needs openapi-generator)
+    python scripts/regen.py --check    # exit 1 if a regen would change spec or tree
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[3]
+GOLDEN = REPO / "tests" / "golden" / "openapi.json"
+OUT = Path(__file__).resolve().parents[1] / "src" / "qqflow_sdk" / "generated"
+PKG = OUT.parent.name          # the generated package directory (its import root)
+PKGDIR = Path(__file__).resolve().parents[1]      # clients/python
+CONFIG = PKGDIR / "openapitools.json"             # pins the generator jar version
+# The wrapper version is pinned in the npx call itself: the floating default
+# would let a new wrapper (or its default jar) change generation without any
+# repo change - exactly what the no-diff gate must be able to blame.
+WRAPPER = "@openapitools/openapi-generator-cli@2.41.0"
+
+
+def normalize(node):
+    """3.1-to-3.0 normalization, in place. Deterministic."""
+    if isinstance(node, list):
+        for item in node:
+            normalize(item)
+        return
+    if not isinstance(node, dict):
+        return
+    types = node.get("type")
+    if isinstance(types, list) and len(types) == 2 and "null" in types:
+        rest = [t for t in types if t != "null"]
+        node["nullable"] = True
+        node["type"] = rest[0] if len(rest) == 1 else rest
+    arms = node.get("oneOf")
+    if isinstance(arms, list):
+        kept = [a for a in arms if a.get("type") != "null"]
+        if len(kept) != len(arms):
+            if len(kept) == 1:
+                only = kept[0]
+                node.pop("oneOf")
+                node.update(only)
+            else:
+                node["oneOf"] = kept
+    for value in list(node.values()):
+        normalize(value)
+
+
+def build_spec() -> dict:
+    """Get the normalized 3.0 spec.
+
+    Preferred source: ``cargo run -p qqflow-regen -- --dump-spec`` - the
+    same normalization the Rust client's generator consumes, taken from the
+    live ``document()`` rather than the golden snapshot (whose placeholder
+    masking would burn wrong types - e.g. an integer watermark restored as
+    string - into generated models). Falls back to the snapshot when cargo
+    is unavailable, with a loud warning: the fallback can mis-type masked
+    properties.
+    """
+    import subprocess
+
+    try:
+        raw = subprocess.run(
+            ["cargo", "run", "--locked", "-p", "qqflow-regen", "--", "--dump-spec"],
+            cwd=str(REPO),
+            check=True, capture_output=True, text=True,
+        ).stdout
+        return json.loads(raw)
+    except (OSError, subprocess.CalledProcessError) as exc:
+        print(
+            "WARNING: falling back to the golden snapshot; volatile-masked"
+            " properties will be typed as strings. Reason: "
+            + str(exc),
+            file=sys.stderr,
+        )
+    import re
+
+    doc = json.loads(GOLDEN.read_text(encoding="utf-8"))["body"]
+
+    def restore(node):
+        if isinstance(node, list):
+            for item in node:
+                restore(item)
+            return
+        if not isinstance(node, dict):
+            return
+        for key, value in list(node.items()):
+            if value == "<volatile>":
+                node[key] = {"type": "string"}
+            else:
+                restore(value)
+
+    restore(doc)
+    normalize(doc)
+    doc["openapi"] = "3.0.3"
+    for path, item in doc.get("paths", {}).items():
+        names = re.findall(r"\{(\w+)\}", path)
+        if not names:
+            continue
+        for op in item.values():
+            if not isinstance(op, dict):
+                continue
+            op["parameters"] = [
+                {
+                    "name": name,
+                    "in": "path",
+                    "required": True,
+                    "style": "simple",
+                    "schema": {"type": "string"},
+                }
+                for name in names
+            ]
+    return doc
+
+def tree_digest(root: Path) -> str:
+    # Byte-compiled artifacts are excluded deliberately: a local pytest run
+    # drops __pycache__/*.pyc INSIDE the generated tree (the scratch
+    # regeneration never makes them), and without this filter the digest
+    # gate reports a false "stale tree" on a byte-identical checkout.
+    sha = hashlib.sha256()
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        if "__pycache__" in path.parts or path.suffix == ".pyc":
+            continue
+        sha.update(str(path.relative_to(root)).encode())
+        sha.update(path.read_bytes())
+    return sha.hexdigest()
+
+
+def normalize_generated(root: Path) -> int:
+    """Strip trailing whitespace and trailing blank lines from generated files.
+
+    The generator leaves trailing spaces inside docstrings and a blank line at the
+    end of several files. This repository checks whitespace with ``git diff
+    --check`` against the empty tree, so a committed file is inspected forever -
+    not only in the change that introduced it: a single unnormalized regeneration
+    turns the whole-repository check red and stays red until the bytes change.
+    Normalizing inside the pipeline keeps every regeneration clean without editing
+    ``generated/`` by hand, which the module docstring forbids.
+
+    Returns the number of files rewritten.
+    """
+    changed = 0
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        raw = path.read_bytes()
+        try:
+            text = raw.decode("utf-8")
+        except UnicodeDecodeError:
+            continue
+        lines = [line.rstrip() for line in text.splitlines()]
+        while lines and not lines[-1]:
+            lines.pop()
+        fixed = ("\n".join(lines) + "\n").encode("utf-8") if lines else b""
+        if fixed != raw:
+            path.write_bytes(fixed)
+            changed += 1
+    return changed
+
+
+def write_spec(spec, path):
+    text = json.dumps(spec, indent=2, ensure_ascii=False, sort_keys=True) + "\n"
+    path.write_text(text, encoding="utf-8")
+    return text
+
+
+def generate_tree(spec_path, dest_root):
+    # Run the generator from spec_path into dest_root/PKG, keeping only the
+    # library face, rewriting the absolute imports the generator emits
+    # (nested under our package they would resolve to the handwritten one),
+    # and normalizing whitespace. Returns the number of files normalized.
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_out = Path(tmp) / "gen"
+        cmd = ["npx.cmd" if sys.platform == "win32" else "npx",
+               "--yes", WRAPPER,
+               "--openapitools", str(CONFIG),
+               "generate",
+               "-i", str(spec_path),
+               "-g", "python",
+               "-o", str(tmp_out),
+               "--package-name", PKG,
+               "--library", "httpx"]
+        subprocess.run(cmd, check=True, cwd=str(PKGDIR))
+        shutil.copytree(tmp_out / PKG, dest_root / PKG)
+    pkg_dir = dest_root / PKG
+    for py_file in pkg_dir.rglob("*.py"):
+        text = py_file.read_text(encoding="utf-8")
+        fixed = (
+            text
+            .replace("from " + PKG + ".", "from " + PKG + ".generated." + PKG + ".")
+            .replace("from " + PKG + " import",
+                     "from " + PKG + ".generated." + PKG + " import")
+            .replace("import " + PKG + ".", "import " + PKG + ".generated." + PKG + ".")
+        )
+        if fixed != text:
+            py_file.write_text(fixed, encoding="utf-8")
+    return normalize_generated(dest_root)
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--check", action="store_true",
+                        help="fail if a regeneration would change spec or the tree")
+    args = parser.parse_args()
+
+    spec = build_spec()
+    fresh_spec = json.dumps(spec, indent=2, ensure_ascii=False, sort_keys=True) + "\n"
+
+    if args.check:
+        # The digest half of --check actually runs the generator (unlike the
+        # old spec-only check), so CI needs node/npx + a JRE. Fail with a
+        # readable line instead of a subprocess traceback.
+        import shutil as _shutil
+        npx = "npx.cmd" if sys.platform == "win32" else "npx"
+        if _shutil.which(npx) is None:
+            print("regen --check needs npx (Node.js) on PATH to regenerate the tree",
+                  file=sys.stderr)
+            return 1
+        # Two comparisons, because "the spec did not change" is NOT the gate
+        # it looks like: model output and whitespace can drift while the
+        # description stays byte-identical (generator version, templates).
+        # The whole tree is regenerated into a scratch dir and compared by
+        # digest; spec equality alone could not see any of that.
+        committed_spec = (OUT / "spec.json").read_text(encoding="utf-8")
+        if committed_spec != fresh_spec:
+            print("generated spec is stale: rerun scripts/regen.py and commit",
+                  file=sys.stderr)
+            return 1
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_spec = Path(tmp) / "spec.json"
+            tmp_spec.write_text(fresh_spec, encoding="utf-8")
+            gen_root = Path(tmp) / "tree"
+            gen_root.mkdir()
+            generate_tree(tmp_spec, gen_root)
+            fresh_digest = tree_digest(gen_root / PKG)
+        committed_digest = tree_digest(OUT / PKG)
+        if fresh_digest != committed_digest:
+            print("generated tree is stale: rerun scripts/regen.py and commit\n"
+                  "  committed    " + committed_digest + "\n"
+                  "  regenerated  " + fresh_digest, file=sys.stderr)
+            return 1
+        print("generated spec and tree are up to date:", OUT, fresh_digest[:12])
+        return 0
+
+    OUT.mkdir(parents=True, exist_ok=True)
+    spec_path = OUT / "spec.json"
+    write_spec(spec, spec_path)
+
+    for child in OUT.iterdir():
+        if child.name != "spec.json":
+            shutil.rmtree(child) if child.is_dir() else child.unlink()
+    normalized = generate_tree(spec_path, OUT)
+    print("regenerated: " + str(OUT) + " (normalized " + str(normalized) + " files)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

qqflow_sdk-0.9.0/src/qqflow_sdk/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ren-yc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qqflow_sdk-0.9.0/src/qqflow_sdk/__init__.py

@@ -0,0 +1,39 @@
+"""Typed Python client for qqflow-server.
+
+Two layers with different ownership:
+
+- :mod:`qqflow_sdk.generated` - request/response models produced from the
+  server's OpenAPI description. Never edit by hand; rerun
+  ``scripts/regen.py`` and commit the result (CI asserts no diff).
+- :mod:`qqflow_sdk.client` - the handwritten behavior layer (readiness
+  polling, cursor draining, SSE watching, media retries). This is the API
+  most downstreams should use.
+"""
+
+from .client import (
+    CONNECT_TIMEOUT,
+    READ_TIMEOUT,
+    STALL_TIMEOUT,
+    BadDate,
+    Client,
+    ClientError,
+    MessageEvent,
+    NotReady,
+    ShapeError,
+    StatusError,
+    TransportError,
+)
+
+__all__ = [
+    "CONNECT_TIMEOUT",
+    "READ_TIMEOUT",
+    "STALL_TIMEOUT",
+    "BadDate",
+    "Client",
+    "ClientError",
+    "MessageEvent",
+    "NotReady",
+    "ShapeError",
+    "StatusError",
+    "TransportError",
+]