jiuzhang-sdk 0.1.0a10__tar.gz

jiuzhang_sdk-0.1.0a10/.gitignore

@@ -0,0 +1,112 @@
+# ---------- Python ----------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Build & dist
+build/
+dist/
+release/
+*.egg-info/
+*.egg
+*.whl
+*.tar.gz
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+uv.lock.bak
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checkers & linters
+.mypy_cache/
+.ruff_cache/
+.pytype/
+.dmypy.json
+dmypy.json
+
+# Docs build
+docs/_build/
+site/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# ---------- IDE ----------
+.idea/
+.vscode/
+.claude/
+*.swp
+*.swo
+*~
+
+# ---------- OS ----------
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ---------- 项目私密 ----------
+群聊记录/
+*.local.md
+.env
+.env.*
+!.env.example
+doc/~$*
+*.pptx
+Claude Conversations/
+
+# Python
+.eggs/
+
+# IDE
+remote/
+
+# Claude Code local settings
+.claude/settings.local.json
+# Python-generated files
+*.py[oc]
+*.egg-info
+
+# IDE
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Logs
+logs/
+*.log
+*.log.*
+
+# OS
+dataset/
+.claude
+
+debug/
+debug.ipynb
+.agents/
+.codex/
+
+# user
+/remote
+/daily_report

jiuzhang_sdk-0.1.0a10/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: jiuzhang-sdk
+Version: 0.1.0a10
+Summary: 九章光量子真机云接入软件包（jiuzhang SDK）
+Author: 九章量子 SDK 团队
+License: Proprietary
+Keywords: gbs,jiuzhang,photonic,quantum,sdk
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=3.8; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-mock>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: jupyter
+Requires-Dist: ipython>=8; extra == 'jupyter'
+Description-Content-Type: text/markdown
+
+# jiuzhang SDK 开发说明
+
+本目录是 `jiuzhang` Python SDK 的源码工程。仓库根 `README.md` 面向用户和外部
+协作方，本文件面向 SDK 开发维护。
+
+## 当前主线
+
+当前主线是九章云平台 HTTP SDK：
+
+```text
+Python / Jupyter
+  -> jiuzhang SDK
+  -> 九章云平台 API / 本地九章云平台 Mock
+  -> 天衍适配器
+  -> 天衍平台 / tianyan-Mock
+```
+
+SDK 不直接请求天衍平台，不直接请求 tianyan-Mock，也不保留早期 TCP 真机直连
+协议线。
+
+## 工程结构
+
+```text
+code/
+├── pyproject.toml
+├── README.md
+├── src/jiuzhang/
+│   ├── __init__.py
+│   ├── auth/              # TokenManager
+│   ├── cloud/             # CloudClient / HttpTransport
+│   ├── gbs/               # GBSParams / GBSResult / analysis / mock
+│   ├── jupyter.py         # Notebook helpers
+│   ├── settings.py        # Settings.from_env()
+│   ├── errors.py
+│   ├── exceptions.py
+│   └── result.py
+└── tests/
+    ├── unit/
+    └── integration/
+```
+
+## 本地开发
+
+使用本机 `jzsdk` conda 环境：
+
+```powershell
+conda activate jzsdk
+cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk\code
+pip install -e ".[dev,jupyter]"
+```
+
+质量检查：
+
+```powershell
+ruff format src tests
+ruff check src tests
+mypy src
+pytest tests
+```
+
+## 公开 API
+
+```python
+from jiuzhang import CloudClient, TokenManager
+from jiuzhang import GBSParams, GBSResult, parse_gbs_result
+from jiuzhang.gbs.analysis import photon_count_histogram
+from jiuzhang.gbs.mock import generate_mock_samples
+```
+
+## 云平台接口
+
+SDK 当前请求九章云平台公开接口：
+
+```text
+POST /estimate
+POST /tasks/submit
+GET  /tasks/{task_id}
+```
+
+认证头：
+
+```text
+X-Jiuzhang-API-Key: <api_key>
+```
+
+提交任务时自动携带：
+
+```text
+X-Request-Id: <uuid>
+```
+
+所有云平台响应先检查 `code`，只有 `code == 0` 才视为业务成功。
+
+## 本地 Mock
+
+```powershell
+cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk
+python local_test/mock_cloud_platform/mock_cloud_platform.py --port 18081 --mode standalone
+```
+
+SDK 测试和示例中的 `base_url` 指向本地九章云平台 Mock：
+
+```text
+http://127.0.0.1:18081
+```
+
+## 版本
+
+当前版本：`0.1.0a10`。
+
+## License
+
+Proprietary — Copyright © 2026 九章量子.

jiuzhang_sdk-0.1.0a10/README.md

@@ -0,0 +1,113 @@
+# jiuzhang SDK 开发说明
+
+本目录是 `jiuzhang` Python SDK 的源码工程。仓库根 `README.md` 面向用户和外部
+协作方，本文件面向 SDK 开发维护。
+
+## 当前主线
+
+当前主线是九章云平台 HTTP SDK：
+
+```text
+Python / Jupyter
+  -> jiuzhang SDK
+  -> 九章云平台 API / 本地九章云平台 Mock
+  -> 天衍适配器
+  -> 天衍平台 / tianyan-Mock
+```
+
+SDK 不直接请求天衍平台，不直接请求 tianyan-Mock，也不保留早期 TCP 真机直连
+协议线。
+
+## 工程结构
+
+```text
+code/
+├── pyproject.toml
+├── README.md
+├── src/jiuzhang/
+│   ├── __init__.py
+│   ├── auth/              # TokenManager
+│   ├── cloud/             # CloudClient / HttpTransport
+│   ├── gbs/               # GBSParams / GBSResult / analysis / mock
+│   ├── jupyter.py         # Notebook helpers
+│   ├── settings.py        # Settings.from_env()
+│   ├── errors.py
+│   ├── exceptions.py
+│   └── result.py
+└── tests/
+    ├── unit/
+    └── integration/
+```
+
+## 本地开发
+
+使用本机 `jzsdk` conda 环境：
+
+```powershell
+conda activate jzsdk
+cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk\code
+pip install -e ".[dev,jupyter]"
+```
+
+质量检查：
+
+```powershell
+ruff format src tests
+ruff check src tests
+mypy src
+pytest tests
+```
+
+## 公开 API
+
+```python
+from jiuzhang import CloudClient, TokenManager
+from jiuzhang import GBSParams, GBSResult, parse_gbs_result
+from jiuzhang.gbs.analysis import photon_count_histogram
+from jiuzhang.gbs.mock import generate_mock_samples
+```
+
+## 云平台接口
+
+SDK 当前请求九章云平台公开接口：
+
+```text
+POST /estimate
+POST /tasks/submit
+GET  /tasks/{task_id}
+```
+
+认证头：
+
+```text
+X-Jiuzhang-API-Key: <api_key>
+```
+
+提交任务时自动携带：
+
+```text
+X-Request-Id: <uuid>
+```
+
+所有云平台响应先检查 `code`，只有 `code == 0` 才视为业务成功。
+
+## 本地 Mock
+
+```powershell
+cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk
+python local_test/mock_cloud_platform/mock_cloud_platform.py --port 18081 --mode standalone
+```
+
+SDK 测试和示例中的 `base_url` 指向本地九章云平台 Mock：
+
+```text
+http://127.0.0.1:18081
+```
+
+## 版本
+
+当前版本：`0.1.0a10`。
+
+## License
+
+Proprietary — Copyright © 2026 九章量子.

jiuzhang_sdk-0.1.0a10/pyproject.toml

@@ -0,0 +1,141 @@
+[project]
+name = "jiuzhang-sdk"
+version = "0.1.0a10"
+description = "九章光量子真机云接入软件包（jiuzhang SDK）"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Proprietary" }
+authors = [
+    { name = "九章量子 SDK 团队" },
+]
+keywords = ["quantum", "photonic", "gbs", "jiuzhang", "sdk"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "httpx>=0.27",
+    "numpy>=1.26",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "pytest-mock>=3",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pre-commit>=3.8",
+]
+jupyter = [
+    "ipython>=8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jiuzhang"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/jiuzhang",
+    "tests",
+    "README.md",
+    "pyproject.toml",
+]
+
+# -------------------------------------------------------------------
+# ruff: 格式化 + lint + import 排序 + docstring 规范
+# -------------------------------------------------------------------
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+extend-exclude = [".venv", "dist", "build"]
+
+[tool.ruff.lint]
+# E/W: pycodestyle, F: pyflakes, I: isort, N: pep8-naming, UP: pyupgrade,
+# B: flake8-bugbear, SIM: flake8-simplify, RUF: ruff-specific,
+# D: pydocstyle (启用 Google 风格 docstring 校验)
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF", "D"]
+ignore = [
+    # 模块级 docstring 不强制（D100 模块、D104 包 __init__）
+    "D100",
+    "D104",
+    # 中文 docstring 适配：句号 "。" 不被 D415 识别为结束符
+    "D415",
+    # 中文 docstring/字符串/注释允许使用全角标点（，。：；（））
+    "RUF001",
+    "RUF002",
+    "RUF003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# 测试代码不要求 docstring
+"tests/**" = ["D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+# -------------------------------------------------------------------
+# mypy: 严格类型检查
+# -------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+show_error_codes = true
+show_column_numbers = true
+
+# -------------------------------------------------------------------
+# pytest: 测试配置
+# -------------------------------------------------------------------
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--cov=jiuzhang",
+    "--cov-report=term-missing",
+]
+markers = [
+    "unit: 单元测试（默认）",
+    "integration: 集成测试（需要本地 Mock 或外部 HTTP 服务）",
+    "slow: 慢测试（默认跳过）",
+]
+
+# -------------------------------------------------------------------
+# coverage: 覆盖率配置
+# -------------------------------------------------------------------
+[tool.coverage.run]
+source = ["jiuzhang"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]

jiuzhang_sdk-0.1.0a10/src/jiuzhang/__init__.py

@@ -0,0 +1,56 @@
+"""jiuzhang — 九章光量子云接入 Python SDK。
+
+公开 API 由本模块的 ``__all__`` 锁定。未在其中列出的符号视为内部实现，
+任何版本均可能变更。集成方应通过::
+
+    from jiuzhang import CloudClient, TokenManager
+
+的方式引用，避免直接 import 子模块的私有路径。
+"""
+
+from __future__ import annotations
+
+from jiuzhang.auth import TokenManager
+from jiuzhang.cloud import CloudClient, HttpTransport
+from jiuzhang.errors import _populate_error_code_to_exception
+from jiuzhang.exceptions import (
+    InternalError,
+    InvalidParameterError,
+    JiuzhangError,
+    MachineBusyError,
+    MachineOfflineError,
+    PermissionDeniedError,
+    TimeoutError,
+    TokenExpiredError,
+    TokenInvalidError,
+)
+from jiuzhang.gbs import GBSParams, GBSResult, input_mode_count, output_mode_count, parse_gbs_result
+from jiuzhang.settings import Settings
+from jiuzhang.version import __version__
+
+# 在所有异常类完成导入后填充错误码 → 异常类映射，打破 errors.py 与
+# exceptions.py 之间的循环依赖。
+_populate_error_code_to_exception()
+del _populate_error_code_to_exception
+
+__all__ = [
+    "CloudClient",
+    "GBSParams",
+    "GBSResult",
+    "HttpTransport",
+    "InternalError",
+    "InvalidParameterError",
+    "JiuzhangError",
+    "MachineBusyError",
+    "MachineOfflineError",
+    "PermissionDeniedError",
+    "Settings",
+    "TimeoutError",
+    "TokenExpiredError",
+    "TokenInvalidError",
+    "TokenManager",
+    "__version__",
+    "input_mode_count",
+    "output_mode_count",
+    "parse_gbs_result",
+]

jiuzhang_sdk-0.1.0a10/src/jiuzhang/auth/__init__.py

@@ -0,0 +1,7 @@
+"""认证模块：token 本地校验与持有。"""
+
+from __future__ import annotations
+
+from jiuzhang.auth.token_manager import TokenManager
+
+__all__ = ["TokenManager"]

jiuzhang_sdk-0.1.0a10/src/jiuzhang/auth/token_manager.py

@@ -0,0 +1,86 @@
+"""TokenManager — API Key 本地格式校验与持有。
+
+当前九章云平台 API Key 真实格式尚未冻结，SDK 暂接受 ``JZ-`` 或 ``PQ-``
+前缀 + 32 位十六进制小写字符作为本地占位校验规则，例如::
+
+    JZ-3f2c2a3b0f7a4a2ab1cdb0b7d2f1a9c4
+    PQ-3f2c2a3b0f7a4a2ab1cdb0b7d2f1a9c4
+
+本模块仅做客户端本地格式校验，**不产生任何网络请求**。后续云平台认证规则
+确定后，应优先在本模块集中调整 API Key 格式校验与脱敏展示逻辑。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from jiuzhang.exceptions import TokenInvalidError
+from jiuzhang.result import make_result
+
+__all__ = ["TokenManager"]
+
+_TOKEN_PATTERN = re.compile(r"^(JZ|PQ)-[0-9a-f]{32}$")
+
+
+class TokenManager:
+    """持有 API Key 并提供本地格式校验。
+
+    Attributes:
+        token_id: 调用方传入的 API Key 字符串。
+
+    Examples:
+        >>> tm = TokenManager(token_id="PQ-3f2c2a3b0f7a4a2ab1cdb0b7d2f1a9c4")
+        >>> result = tm.validate_token()
+        >>> result["code"]
+        'OK'
+    """
+
+    def __init__(self, token_id: str) -> None:
+        """构造 TokenManager。
+
+        Args:
+            token_id: API Key 字符串。本构造函数不做校验，校验在
+                :meth:`validate_token` 中执行。
+        """
+        self.token_id: str = token_id
+
+    @property
+    def masked_token(self) -> str:
+        """脱敏展示：保留前缀与末 4 位，中间用 ``***`` 替代。
+
+        Examples:
+            >>> TokenManager("PQ-3f2c2a3b0f7a4a2ab1cdb0b7d2f1a9c4").masked_token
+            'PQ-3f2c***a9c4'
+        """
+        if len(self.token_id) >= 10:
+            return self.token_id[:7] + "***" + self.token_id[-4:]
+        return "***"
+
+    def validate_token(self) -> dict[str, Any]:
+        """对持有的 API Key 做本地格式校验。
+
+        校验规则：
+
+        * 前缀暂定为 ``JZ-`` 或 ``PQ-``
+        * 前缀后为 32 位十六进制小写字符
+        * 总长度为 35 个字符
+
+        Returns:
+            统一返回结构 dict。校验通过时 ``code == "OK"``，
+            ``data`` 含 ``tokenId``（脱敏）与 ``format``（``"VALID"``）。
+
+        Raises:
+            TokenInvalidError: 格式不符合规则。
+        """
+        if not _TOKEN_PATTERN.match(self.token_id):
+            raise TokenInvalidError(
+                "API Key 格式非法：期望 'JZ-' 或 'PQ-' + 32 位十六进制小写，"
+                f"实际为 {self.masked_token!r}",
+                details={"token_masked": self.masked_token},
+            )
+
+        return make_result(
+            message="token 校验通过",
+            data={"tokenId": self.masked_token, "format": "VALID"},
+        )

jiuzhang_sdk-0.1.0a10/src/jiuzhang/cloud/__init__.py

@@ -0,0 +1,8 @@
+"""九章云平台 HTTP 客户端主线。"""
+
+from __future__ import annotations
+
+from jiuzhang.cloud.client import CloudClient
+from jiuzhang.cloud.transport import HttpTransport
+
+__all__ = ["CloudClient", "HttpTransport"]