qatlas-cli 0.22.0__tar.gz

qatlas_cli-0.22.0/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+# Release pipeline: tag push (v*) → build sdist/wheel → PyPI.
+#
+# PyPI publication uses Trusted Publishing via OIDC — no API token is
+# stored anywhere. PyPI verifies the GitHub OIDC token against a
+# per-project Trusted Publisher config that must match:
+#
+#   PyPI project name:    qatlas-cli
+#   Owner:                IAI-USTC-Quantum
+#   Repository name:      qatlas-cli
+#   Workflow filename:    release.yml
+#   Environment name:     pypi
+#
+# One-time setup: configure the publisher at
+#   https://pypi.org/manage/project/qatlas-cli/settings/publishing/
+# and create a GitHub Environment named `pypi` in repo Settings
+# (no secrets / approval reviewers needed — the name itself is the
+# match key for the OIDC token).
+#
+# `skip-existing: true` makes re-runs against an already-published
+# version a no-op.
+
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/qatlas-cli/
+    permissions:
+      contents: read  # checkout the tagged ref
+      id-token: write # required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Verify tag matches pyproject version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PYPROJECT_VERSION="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [ "$TAG" != "$PYPROJECT_VERSION" ]; then
+            echo "tag v$TAG does not match pyproject version $PYPROJECT_VERSION" >&2
+            exit 1
+          fi
+
+      - name: Build Python distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Silent no-op on re-runs against already-published versions.
+          skip-existing: true

qatlas_cli-0.22.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+
+# Virtualenvs
+.venv/
+.venv-*/
+venv/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

qatlas_cli-0.22.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.22.0
+
+- 仓库迁移至 IAI-USTC-Quantum/qatlas-cli；安装方式与版本血统继承自
+  主仓 `quantum-atlas` 包。
+- 新增 PyPI Trusted Publishing 发布流程（tag `v*` 触发）。
+
+## 0.21.0a3
+
+- CLI 从主仓 QuantumAtlas 拆分为独立仓库；版本号自主仓 `quantum-atlas`
+  包的 0.21.0a3 继承延续，不重新从 0.x 计数。
+- 安装方式与拆分前一致：`uv tool install qatlas-cli`（PyPI）。
+- 发布流程：commitizen（`cz bump`，tag 格式 `v<version>`）打 tag 后由
+  `.github/workflows/release.yml` 经 PyPI Trusted Publishing 自动发布。

qatlas_cli-0.22.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: qatlas-cli
+Version: 0.22.0
+Summary: Command-line client for QuantumAtlas (qatlas CLI)
+Author: IAI-USTC-Quantum
+Keywords: cli,client,papers,quantum
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: pydantic-settings<3,>=2.0.0
+Requires-Dist: pydantic<3,>=2.5.0
+Requires-Dist: pyyaml<7,>=6.0.1
+Requires-Dist: requests<3,>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qatlas-cli — QuantumAtlas 的命令行客户端
+
+> QuantumAtlas 的 `qatlas` 命令行客户端：面向用户侧的论文获取、贡献上传、
+> 本地解析等工作流，通过 HTTP 与服务端 qatlasd 交互。本仓库是主仓
+> QuantumAtlas 拆出的独立私有仓库，只保留客户端与本地工具，不含服务端代码。
+
+所有服务端通信都是 `requests` 直发的 HTTP 调用，无重量级 SDK 依赖。
+
+## 安装
+
+从 PyPI 安装为全局 CLI 工具（推荐，与拆分前 `quantum-atlas` 的安装方式一致）：
+
+```bash
+# 推荐：uv 全局工具（隔离环境 + 升级方便）
+uv tool install qatlas-cli
+
+# 或 pipx
+pipx install qatlas-cli
+
+# 或 plain pip
+pip install qatlas-cli
+
+qatlas --help
+```
+
+也可以直接从 GitHub 安装：
+
+```bash
+uv tool install --from git+ssh://git@github.com/IAI-USTC-Quantum/qatlas-cli.git qatlas-cli
+```
+
+本地 editable 安装（开发用）：
+
+```bash
+git clone git@github.com:IAI-USTC-Quantum/qatlas-cli.git
+cd qatlas-cli
+uv sync --extra dev          # 项目内 .venv，editable 安装本包
+# 或装入当前环境：
+uv pip install -e .
+```
+
+## 命令概览
+
+```
+qatlas config   # 管理用户级配置文件（~/.config/qatlas/config.yaml）
+qatlas auth     # 管理各 host 的 PAT / session token（login / status / token / logout）
+qatlas paper    # 从服务端拉取论文 PDF / markdown（静默 fetch + LRO 轮询）
+qatlas contrib  # 贡献者工作流：上传 PDF（contrib pdf）或本地跑 MinerU 再推送（contrib mineru）
+qatlas parser   # 抓取并解析 arXiv 论文（本地工作区命令）
+```
+
+别名：`papers` → `paper`，`parse` → `parser`。
+
+```bash
+qatlas auth login                                   # 设备码 / PAT 登录
+qatlas paper get markdown quant-ph/9508027 --output paper.md
+qatlas contrib pdf quant-ph/9508027v1 --pdf paper.pdf
+qatlas contrib mineru 2501.00010v1
+```
+
+`search` 命令由独立插件 qatlas-search 提供（仓库 IAI-USTC-Quantum/qatlas-search），
+未安装时 `qatlas search` 会给出安装提示。
+
+### 插件机制
+
+第三方包可以通过 entry point 组 **`qatlas.plugins`** 注册插件，向 CLI 贡献
+顶层命令或 `contrib` 子命令。插件协议（基类 `QatlasPlugin` 与
+`CommandSpec`）定义在 `qatlas/client/plugins/base.py`：
+
+```toml
+# 插件包自己的 pyproject.toml
+[project.entry-points."qatlas.plugins"]
+myplugin = "my_package.qatlas_plugin:plugin"
+```
+
+内置命令优先于插件命令；插件不可用时会被静默跳过，不影响 CLI 本体。
+
+## 配置
+
+用户级配置位于 `~/.config/qatlas/config.yaml`（首次运行非 `config` 命令时
+自动创建），顶层 `server_url` / `token` 等字段供各客户端命令读取。环境变量
+`QATLAS_*` 系列可覆盖对应配置；`QATLAS_SKIP_DOTENV=1` 跳过仓库 `.env` 加载。
+
+## 开发与测试
+
+```bash
+uv sync --extra dev
+uv run pytest -q        # 默认全离线；真打外网的用例标了 network，需 -m network 显式开启
+```
+
+测试覆盖：CLI 命令分发与版本解析、auth（设备码登录 / token 存储，mock HTTP）、
+paper / contrib / config 命令行为（mock 服务端）、parser 的 arXiv 抓取与
+MinerU 客户端（固定 fixture / mock）。带 `network` 标记的 live 用例默认跳过。

qatlas_cli-0.22.0/README.md

@@ -0,0 +1,93 @@
+# qatlas-cli — QuantumAtlas 的命令行客户端
+
+> QuantumAtlas 的 `qatlas` 命令行客户端：面向用户侧的论文获取、贡献上传、
+> 本地解析等工作流，通过 HTTP 与服务端 qatlasd 交互。本仓库是主仓
+> QuantumAtlas 拆出的独立私有仓库，只保留客户端与本地工具，不含服务端代码。
+
+所有服务端通信都是 `requests` 直发的 HTTP 调用，无重量级 SDK 依赖。
+
+## 安装
+
+从 PyPI 安装为全局 CLI 工具（推荐，与拆分前 `quantum-atlas` 的安装方式一致）：
+
+```bash
+# 推荐：uv 全局工具（隔离环境 + 升级方便）
+uv tool install qatlas-cli
+
+# 或 pipx
+pipx install qatlas-cli
+
+# 或 plain pip
+pip install qatlas-cli
+
+qatlas --help
+```
+
+也可以直接从 GitHub 安装：
+
+```bash
+uv tool install --from git+ssh://git@github.com/IAI-USTC-Quantum/qatlas-cli.git qatlas-cli
+```
+
+本地 editable 安装（开发用）：
+
+```bash
+git clone git@github.com:IAI-USTC-Quantum/qatlas-cli.git
+cd qatlas-cli
+uv sync --extra dev          # 项目内 .venv，editable 安装本包
+# 或装入当前环境：
+uv pip install -e .
+```
+
+## 命令概览
+
+```
+qatlas config   # 管理用户级配置文件（~/.config/qatlas/config.yaml）
+qatlas auth     # 管理各 host 的 PAT / session token（login / status / token / logout）
+qatlas paper    # 从服务端拉取论文 PDF / markdown（静默 fetch + LRO 轮询）
+qatlas contrib  # 贡献者工作流：上传 PDF（contrib pdf）或本地跑 MinerU 再推送（contrib mineru）
+qatlas parser   # 抓取并解析 arXiv 论文（本地工作区命令）
+```
+
+别名：`papers` → `paper`，`parse` → `parser`。
+
+```bash
+qatlas auth login                                   # 设备码 / PAT 登录
+qatlas paper get markdown quant-ph/9508027 --output paper.md
+qatlas contrib pdf quant-ph/9508027v1 --pdf paper.pdf
+qatlas contrib mineru 2501.00010v1
+```
+
+`search` 命令由独立插件 qatlas-search 提供（仓库 IAI-USTC-Quantum/qatlas-search），
+未安装时 `qatlas search` 会给出安装提示。
+
+### 插件机制
+
+第三方包可以通过 entry point 组 **`qatlas.plugins`** 注册插件，向 CLI 贡献
+顶层命令或 `contrib` 子命令。插件协议（基类 `QatlasPlugin` 与
+`CommandSpec`）定义在 `qatlas/client/plugins/base.py`：
+
+```toml
+# 插件包自己的 pyproject.toml
+[project.entry-points."qatlas.plugins"]
+myplugin = "my_package.qatlas_plugin:plugin"
+```
+
+内置命令优先于插件命令；插件不可用时会被静默跳过，不影响 CLI 本体。
+
+## 配置
+
+用户级配置位于 `~/.config/qatlas/config.yaml`（首次运行非 `config` 命令时
+自动创建），顶层 `server_url` / `token` 等字段供各客户端命令读取。环境变量
+`QATLAS_*` 系列可覆盖对应配置；`QATLAS_SKIP_DOTENV=1` 跳过仓库 `.env` 加载。
+
+## 开发与测试
+
+```bash
+uv sync --extra dev
+uv run pytest -q        # 默认全离线；真打外网的用例标了 network，需 -m network 显式开启
+```
+
+测试覆盖：CLI 命令分发与版本解析、auth（设备码登录 / token 存储，mock HTTP）、
+paper / contrib / config 命令行为（mock 服务端）、parser 的 arXiv 抓取与
+MinerU 客户端（固定 fixture / mock）。带 `network` 标记的 live 用例默认跳过。

qatlas_cli-0.22.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "qatlas-cli"
+# Version lineage continues from the main-repo `quantum-atlas` package
+# (the CLI was split out at 0.21.0a3); do not restart from 0.x.
+version = "0.22.0"
+description = "Command-line client for QuantumAtlas (qatlas CLI)"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "IAI-USTC-Quantum" }]
+keywords = ["quantum", "papers", "cli", "client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+# Deliberately thin: all server communication is plain `requests` HTTP —
+# no heavyweight SDK dependencies.
+dependencies = [
+    "requests>=2.31.0,<3",
+    "pyyaml>=6.0.1,<7",
+    "platformdirs>=4,<5",
+    "pydantic>=2.5.0,<3",
+    "pydantic-settings>=2.0.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.scripts]
+qatlas = "qatlas.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qatlas"]
+
+# Commitizen: `cz bump` bumps [project].version via the uv provider and
+# tags v<version>; the tag push triggers .github/workflows/release.yml.
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "v$version"
+version_scheme = "pep440"
+version_provider = "uv"
+update_changelog_on_bump = true
+major_version_zero = true
+annotated_tag = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Live-network tests are opt-in: the default run must be fully offline.
+addopts = "-m 'not network'"
+markers = [
+    "network: opt-in tests that call real external APIs",
+    "e2e: end-to-end tests that load the repository .env and exercise real external services",
+]

qatlas_cli-0.22.0/src/qatlas/__init__.py

@@ -0,0 +1,48 @@
+"""
+QuantumAtlas - AI 驱动的量子算法开发辅助系统
+
+核心功能：从论文到可执行量子代码的完整转化链路
+"""
+
+from __future__ import annotations
+
+import tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+
+def _version_from_pyproject() -> str:
+    """Read [project].version from the nearest repo-root pyproject.toml.
+
+    Supports both the legacy flat layout (``qatlas/`` at the repo root,
+    pyproject at ``parents[1]``) and the src layout (``src/qatlas/``,
+    pyproject at ``parents[2]``).
+    """
+    here = Path(__file__).resolve()
+    for parent in (here.parents[1], here.parents[2]):
+        pyproject = parent / "pyproject.toml"
+        if not pyproject.is_file():
+            continue
+        with pyproject.open("rb") as f:
+            data = tomllib.load(f)
+        try:
+            return str(data["project"]["version"])
+        except KeyError:
+            continue
+    raise FileNotFoundError("no pyproject.toml with [project].version found")
+
+
+def _resolve_version() -> str:
+    """Prefer repo pyproject when present, else installed distribution metadata."""
+    try:
+        return _version_from_pyproject()
+    except (FileNotFoundError, KeyError, OSError):
+        try:
+            return version("qatlas-cli")
+        except PackageNotFoundError:
+            return "0+unknown"
+
+
+__version__ = _resolve_version()
+
+__all__ = ["__version__"]

qatlas_cli-0.22.0/src/qatlas/cli.py

@@ -0,0 +1,218 @@
+"""Top-level command-line entry point for QuantumAtlas.
+
+This module backs the ``qatlas`` console script declared in
+``pyproject.toml``.  It intentionally delegates to the existing module CLIs so
+their behavior stays identical to ``python -m qatlas.<module>``.
+"""
+
+from __future__ import annotations
+
+import runpy
+import sys
+from dataclasses import dataclass
+from typing import Mapping, Sequence
+
+from qatlas import __version__
+
+
+@dataclass(frozen=True)
+class Command:
+    """A delegated QuantumAtlas CLI command."""
+
+    module: str
+    summary: str
+    client_friendly: bool = True
+
+
+COMMANDS: Mapping[str, Command] = {
+    "config": Command(
+        "qatlas.client.config",
+        "Manage the user-level config file (~/.config/qatlas/config.yaml)",
+    ),
+    "auth": Command(
+        "qatlas.client.auth",
+        "Manage saved PATs / session tokens per host (login, status, token, logout)",
+    ),
+    "paper": Command(
+        "qatlas.client.paper",
+        "Fetch paper PDF / markdown from the server (silent fetch + LRO polling for cache misses)",
+    ),
+    "contrib": Command(
+        "qatlas.client.contrib",
+        "Contributor workflows: upload PDFs (contrib pdf) or run local MinerU and push (contrib mineru)",
+    ),
+    "parser": Command("qatlas.parser.__main__", "Fetch and parse arXiv papers", False),
+}
+
+ALIASES: Mapping[str, str] = {
+    "papers": "paper",
+    "parse": "parser",
+}
+
+
+def _print_help() -> None:
+    """Print top-level CLI help."""
+
+    print(
+        """QuantumAtlas command line
+
+Usage:
+  qatlas <command> [args...]
+  qatlas --version
+  qatlas --help
+
+Commands:"""
+    )
+
+    print("  Client/operator commands:")
+    for name, command in COMMANDS.items():
+        if not command.client_friendly:
+            continue
+        print(f"    {name:<10} {command.summary}")
+
+    print("\n  Local workspace commands:")
+    for name, command in COMMANDS.items():
+        if command.client_friendly:
+            continue
+        print(f"    {name:<10} {command.summary}")
+
+    # Plugin-contributed top-level commands (only those available in the
+    # current environment). No first-party plugins ship today; third-party
+    # plugins register via the ``qatlas.plugins`` entry-point group.
+    try:
+        from qatlas.client.plugins import registry
+
+        plugin_cmds = registry.top_level_commands()
+    except Exception:
+        plugin_cmds = {}
+    if plugin_cmds:
+        print("\n  Plugin commands:")
+        for name in sorted(plugin_cmds):
+            print(f"    {name:<10} {plugin_cmds[name].summary}")
+
+    print(
+        """
+Aliases:
+  papers -> paper
+  parse -> parser
+
+Examples:
+  qatlas paper get markdown quant-ph/9508027 --output paper.md
+  qatlas paper get pdf 10.1103/PhysRevLett.103.150502 -o paper.pdf
+  qatlas contrib pdf quant-ph/9508027v1 --pdf paper.pdf
+  qatlas contrib mineru 2501.00010v1
+  qatlas contrib mineru --watch
+
+Use "qatlas <command> --help" for command-specific options."""
+    )
+
+
+def _print_usage_error(message: str) -> None:
+    print(f"Error: {message}", file=sys.stderr)
+    print("Run 'qatlas --help' to see available commands.", file=sys.stderr)
+
+
+def _print_search_plugin_hint() -> None:
+    """Explain that ``search`` ships as the standalone qatlas-search plugin."""
+
+    print(
+        "The 'search' command is provided by the standalone plugin "
+        "qatlas-search, which is not installed.\n"
+        "Install it with pip/uv from the private repository "
+        "IAI-USTC-Quantum/qatlas-search, e.g.:\n"
+        "  uv tool install --from git+ssh://git@github.com/IAI-USTC-Quantum/qatlas-search.git qatlas-search\n"
+        "or, into the current environment:\n"
+        "  uv pip install git+ssh://git@github.com/IAI-USTC-Quantum/qatlas-search.git",
+        file=sys.stderr,
+    )
+
+
+def _exit_code(code: object) -> int:
+    """Normalize a child ``SystemExit.code`` value to an integer exit code."""
+
+    if code is None:
+        return 0
+    if isinstance(code, int):
+        return code
+    print(code, file=sys.stderr)
+    return 1
+
+
+def _run_module(module: str, argv0: str, args: Sequence[str]) -> int:
+    """Run a child module as if it had been invoked with ``python -m``."""
+
+    original_argv = sys.argv[:]
+    sys.argv = [argv0, *args]
+    try:
+        try:
+            runpy.run_module(module, run_name="__main__")
+        except SystemExit as exc:
+            return _exit_code(exc.code)
+        return 0
+    finally:
+        sys.argv = original_argv
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the QuantumAtlas CLI."""
+
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    if not args or args[0] in {"-h", "--help"}:
+        _print_help()
+        return 0
+
+    if args[0] in {"-V", "--version"}:
+        print(f"qatlas {__version__}")
+        return 0
+
+    requested_command = args[0].replace("_", "-")
+    command_name = ALIASES.get(requested_command, requested_command)
+    command = COMMANDS.get(command_name)
+
+    # Plugin-contributed top-level commands fill gaps the static table
+    # doesn't cover. Built-ins always take precedence.
+    plugin_spec = None
+    if command is None:
+        try:
+            from qatlas.client.plugins import registry
+
+            plugin_spec = registry.top_level_commands().get(command_name)
+        except Exception:
+            plugin_spec = None
+        if plugin_spec is None:
+            if command_name == "search":
+                _print_search_plugin_hint()
+                return 2
+            _print_usage_error(f"unknown command '{args[0]}'")
+            return 2
+
+    # v0.17.0+: client config lives exclusively in
+    # ~/.config/qatlas/config.yaml. Ensure it exists on first run so
+    # the user can immediately edit it; idempotent on subsequent runs.
+    #
+    # Exception: skip for `qatlas config` itself — its `path` / `show`
+    # subcommands intentionally tolerate a missing file and would
+    # display misleading "auto-created on first read" behaviour
+    # otherwise.
+    if command_name != "config":
+        try:
+            from qatlas.config import ensure_default_config_exists
+            ensure_default_config_exists()
+        except Exception:
+            # Defensive: never block a subcommand on config-file IO;
+            # the embedded defaults work for any read-only command.
+            pass
+
+    if plugin_spec is not None:
+        return plugin_spec.handler(args[1:])
+
+    return _run_module(
+        command.module,
+        argv0=f"qatlas {command_name}",
+        args=args[1:],
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qatlas_cli-0.22.0/src/qatlas/client/__init__.py

@@ -0,0 +1 @@
+"""HTTP client commands for QuantumAtlas."""