unifyport-sdk 0.1.0__tar.gz

unifyport_sdk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

unifyport_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,122 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      - name: Upgrade packaging installer
+        # pip-audit 会审计当前环境，先更新 runner 自带打包工具，避免已修复漏洞污染 SDK 审计结论。
+        run: python -m pip install --upgrade pip "setuptools>=83"
+      - name: Install project
+        run: python -m pip install -e ".[dev]"
+      - name: Check generated files
+        run: python scripts/generate.py --check
+      - name: Check documentation
+        run: python scripts/check_docs.py
+      - name: Check public repository boundary
+        run: python scripts/check_public.py
+      - name: Check format
+        run: ruff format --check .
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy --strict src scripts typing_tests
+      - name: Check PEP 728 public typing
+        # mypy 2.3 尚未实现 extra_items；Pyright gate 验证 open ProviderProfile 的标准语义。
+        run: npx --yes pyright@1.1.411 pyright_tests
+      - name: Test
+        run: pytest
+      - name: Audit dependencies
+        run: pip-audit
+
+  compatibility:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install project
+        run: python -m pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest
+
+  node-parity:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: python-sdk
+      - uses: actions/checkout@v4
+        with:
+          repository: Unify-Port/UnifyPort-SDK-Nodejs
+          ref: v0.4.0
+          fetch-depth: 0
+          path: node-sdk
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: python-sdk/pyproject.toml
+      - name: Install parity dependencies
+        working-directory: python-sdk
+        run: python -m pip install -e ".[dev]"
+      - name: Verify frozen Node baseline
+        working-directory: python-sdk
+        # 独立 checkout 防止本仓库相对路径或本机状态掩盖 upstream drift。
+        run: python scripts/check_node_parity.py --node-repo ../node-sdk --node-ref v0.4.0
+
+  package:
+    needs: [quality, compatibility, node-parity]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install build tools
+        run: python -m pip install -e ".[dev]"
+      - name: Build distributions
+        run: python -m build
+      - name: Check distributions
+        run: twine check dist/*
+      - name: Inspect public artifacts
+        run: python scripts/check_public.py dist/*
+      - name: Create clean wheel environment
+        # 独立 venv 避免 editable source checkout 掩盖 wheel 的缺失文件或 metadata 问题。
+        run: python -m venv /tmp/unifyport-sdk-wheel-venv
+      - name: Install built wheel
+        run: /tmp/unifyport-sdk-wheel-venv/bin/python -m pip install dist/*.whl
+      - name: Smoke test installed wheel
+        run: /tmp/unifyport-sdk-wheel-venv/bin/python scripts/smoke_installed.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: unifyport-sdk-dist
+          path: dist/*
+          if-no-files-found: error

unifyport_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,148 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+# 同一版本不能覆盖上传，禁止自动取消已进入 registry publish 的 release run。
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Validate and build distributions
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.package-version.outputs.value }}
+    steps:
+      # release job 具有供应链影响，固定第三方 action SHA，避免浮动 tag 在无审查时改变行为。
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Check public repository boundary
+        # Node parity 基准包含其自身的发布配置，先扫描本仓库，避免只读上游 checkout 污染公开边界结论。
+        run: python scripts/check_public.py
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          repository: Unify-Port/UnifyPort-SDK-Nodejs
+          ref: v0.4.0
+          fetch-depth: 0
+          path: node-sdk
+          persist-credentials: false
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: "24"
+          package-manager-cache: false
+      - name: Upgrade audited packaging tools
+        # pip-audit 会检查 runner 环境，先升级已知修复版本，避免基础镜像工具链污染 SDK 结论。
+        run: python -m pip install --upgrade pip "setuptools>=83"
+      - name: Install project
+        run: python -m pip install -e ".[dev]"
+      - name: Read package version
+        id: package-version
+        run: echo "value=$(python -c 'import unifyport; print(unifyport.__version__)')" >> "$GITHUB_OUTPUT"
+      - name: Match tag to package version
+        # tag 与 wheel metadata 不一致会留下无法修正的 registry 版本，因此在 build 前立即失败。
+        env:
+          PACKAGE_VERSION: ${{ steps.package-version.outputs.value }}
+        run: test "$GITHUB_REF_NAME" = "v$PACKAGE_VERSION"
+      - name: Check generated files
+        run: python scripts/generate.py --check
+      - name: Check Node contract parity
+        run: python scripts/check_node_parity.py --node-repo node-sdk --node-ref v0.4.0
+      - name: Check documentation
+        run: python scripts/check_docs.py
+      - name: Check format
+        run: ruff format --check .
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy --strict src scripts typing_tests
+      - name: Check PEP 728 public typing
+        run: npx --yes pyright@1.1.411 pyright_tests
+      - name: Test
+        run: pytest
+      - name: Audit dependencies
+        run: pip-audit
+      - name: Build distributions
+        run: python -m build
+      - name: Check distributions
+        run: twine check dist/*
+      - name: Inspect public artifacts
+        run: python scripts/check_public.py dist/*
+      - name: Install wheel in a clean environment
+        run: |
+          python -m venv /tmp/unifyport-release-wheel-venv
+          /tmp/unifyport-release-wheel-venv/bin/python -m pip install dist/*.whl
+          /tmp/unifyport-release-wheel-venv/bin/python scripts/smoke_installed.py
+      - name: Print distribution checksums
+        run: sha256sum dist/*
+      - name: Store distributions
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: unifyport-sdk-dist-${{ github.ref_name }}
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 90
+
+  publish-pypi:
+    name: Publish to PyPI
+    # 用户确认首发跳过 TestPyPI；仍由 build 全门禁与 pypi environment 审批保护正式发布。
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/unifyport-sdk
+    permissions:
+      id-token: write
+    steps:
+      # production publish 只接收同一 run 的 build 验收 artifact，并由 pypi environment 提供人工审批门禁。
+      - name: Download distributions
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: unifyport-sdk-dist-${{ github.ref_name }}
+          path: dist/
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          print-hash: true
+
+  verify-pypi:
+    name: Verify PyPI installation
+    needs: [build, publish-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+      - name: Install exact PyPI version
+        env:
+          PACKAGE_VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          python -m venv /tmp/unifyport-pypi-venv
+          for attempt in {1..12}; do
+            if /tmp/unifyport-pypi-venv/bin/python -m pip install \
+              --index-url https://pypi.org/simple/ "unifyport-sdk==$PACKAGE_VERSION"; then
+              break
+            fi
+            if [ "$attempt" -eq 12 ]; then
+              exit 1
+            fi
+            sleep 10
+          done
+      - name: Smoke test PyPI installation
+        run: /tmp/unifyport-pypi-venv/bin/python scripts/smoke_installed.py

unifyport_sdk-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+htmlcov/
+
+# 本地环境文件可能包含 credential，始终排除在版本控制之外。
+.env
+.env.*
+!.env.example

unifyport_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+本文件适用于整个仓库，约束自动化 agent 与维护者的协作方式。
+
+## 语言与注释
+
+- 默认使用简体中文协作；代码标识符、命令、配置键、协议字段和错误码保持英文。
+- 英文是公开文档的默认入口；修改用户文档时同步更新完整的简体中文版本。
+- 代码注释只用简短中文解释 why：边界、兼容性、外部限制或风险，不逐行翻译实现。
+
+## 范围与来源
+
+- 本仓库只覆盖公开的 UnifyPort Device API。
+- `contracts/device.openapi.yaml` 是唯一协议生成输入；不得根据未公开实现推断字段或行为。
+- `policy/operation-policies.json` 记录不能从 HTTP method 推导的重试、破坏性和 secret 分类。
+- 不要手改 `src/unifyport/_generated/`；修改 contract、policy 或生成器后运行生成命令。
+- 不提供 generic `raw_request`、MCP、Agent Skills 或 provider-specific orchestration。
+
+## 安全不变量
+
+- `X-Api-Key` 只能来自 client config，operation input 不得覆盖它。
+- 默认只允许 HTTPS；显式 opt-in 的明文 HTTP 也仅限 loopback。
+- 自动重试只适用于 policy allowlist；单次调用只能收紧全局 timeout 和 retry budget。
+- redirect、跨 origin、base path 逃逸、无限分页和无上限响应体必须拒绝。
+- 公开错误和 `ApiResult` 不得携带 raw HTTP response、credential、query、响应正文或底层异常文本。
+- `provider_profile` 与 `reply_token` 按敏感输出处理；fixture、日志和文档不得包含真实 secret。
+
+## 修改流程
+
+1. 先检查 worktree、真实文件和既有测试，保留用户及其他 agent 的改动。
+2. API 变化按 contract → policy → generated code → runtime/tests/docs 的顺序处理。
+3. 新 operation 必须显式分类 auth、mutability、retry、secret input/output 与 parity。
+4. 保持最小改动，不做无关重构或依赖升级。
+5. 交付前运行并如实报告生成、格式、lint、type、test、build、artifact、audit 和 clean-install 门禁。
+
+## 常用验收
+
+```bash
+python scripts/generate.py --check
+python scripts/check_node_parity.py --node-repo ../unifyport-sdk-node --node-ref v0.4.0
+ruff format --check .
+ruff check .
+mypy --strict src scripts typing_tests
+npx --yes pyright@1.1.411 pyright_tests
+pytest
+python -m build
+twine check dist/*
+python scripts/check_public.py dist/*
+python scripts/smoke_installed.py
+pip-audit
+```

unifyport_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable SDK changes are documented here. The format follows Keep a Changelog, and the project uses
+Semantic Versioning for the Python distribution.
+
+## [0.1.0] - 2026-07-31
+
+### Added
+
+- Initial synchronous and asynchronous Device API clients.
+- Generated coverage for the Node SDK `v0.4.0` public surface: 64 operations and 70 schemas.
+- Security-oriented transport, error, retry, timeout, response-size, and pagination behavior.
+- Deterministic generation, parity, packaging, public artifact, and bilingual documentation gates.
+
+[0.1.0]: https://github.com/Unify-Port/UnifyPort-SDK-Python/releases/tag/v0.1.0

unifyport_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UnifyPort
+
+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.

unifyport_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: unifyport-sdk
+Version: 0.1.0
+Summary: Type-safe Python SDK for the UnifyPort Device API.
+Project-URL: Homepage, https://www.unifyport.ai
+Project-URL: Repository, https://github.com/Unify-Port/UnifyPort-SDK-Python
+Project-URL: Issues, https://github.com/Unify-Port/UnifyPort-SDK-Python/issues
+Author: UnifyPort
+License: MIT License
+        
+        Copyright (c) 2026 UnifyPort
+        
+        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.
+License-File: LICENSE
+Keywords: device-api,python,sdk,unifyport
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions<5,>=4.13
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<3,>=1.13; extra == 'dev'
+Requires-Dist: pip-audit<3,>=2.7; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
+Requires-Dist: pytest<10,>=8.3; extra == 'dev'
+Requires-Dist: pyyaml<7,>=6; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Requires-Dist: twine<8,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# UnifyPort Python SDK
+
+[English](https://github.com/Unify-Port/UnifyPort-SDK-Python/blob/main/README.md) |
+[简体中文](https://github.com/Unify-Port/UnifyPort-SDK-Python/blob/main/README.zh-CN.md) |
+[Website](https://www.unifyport.ai)
+
+Type-safe sync and async Python clients for the public UnifyPort Device API. The SDK is generated from
+the approved public OpenAPI contract and currently tracks `@unifyport/sdk-node` `v0.4.0`: 64 operations,
+70 component schemas, and the same retry and secret-handling classifications.
+
+The Python package is `unifyport-sdk`; the import package is `unifyport`. This repository starts at SDK
+version `0.1.0`. A Git tag or local build alone does not prove that a version reached PyPI.
+
+## Requirements
+
+- Python `>=3.11`
+- `httpx` `>=0.27,<1`
+- `typing-extensions` `>=4.13,<5` for the Python 3.11-3.13 PEP 728 backport
+
+Install the published package from PyPI:
+
+```bash
+python -m pip install unifyport-sdk
+```
+
+To work from a source checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+import os
+
+from unifyport import UnifyPortDeviceClient
+
+
+def required_env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise RuntimeError(f"Missing required environment variable: {name}")
+    return value
+
+
+with UnifyPortDeviceClient(
+    base_url=required_env("UNIFYPORT_DEVICE_API_BASE_URL"),
+    api_key=required_env("UNIFYPORT_DEVICE_API_KEY"),
+) as device:
+    workspace = device.get_workspace()
+    print(workspace.data)
+```
+
+The async client exposes the same generated snake_case operation surface:
+
+```python
+import os
+
+from unifyport import AsyncUnifyPortDeviceClient
+
+
+async def main() -> None:
+    async with AsyncUnifyPortDeviceClient(
+        base_url=os.environ["UNIFYPORT_DEVICE_API_BASE_URL"],
+        api_key=os.environ["UNIFYPORT_DEVICE_API_KEY"],
+    ) as device:
+        workspace = await device.get_workspace()
+        print(workspace.data)
+```
+
+Generated operation methods expose path, query, and the allowlisted `x_request_id` header as typed keyword
+arguments, plus typed `body=` and `options=` when applicable. Authentication is never an operation argument:
+
+```python
+account = device.get_account(account_id="acc_example", x_request_id="req_example")
+```
+
+Every call returns `ApiResult[data]` with only filtered metadata: `data`, `status`, and optional
+`request_id`. Raw `httpx.Response` objects are intentionally not public.
+
+## Safety boundaries
+
+- `X-Api-Key` comes only from client configuration and is resolved once per logical operation.
+- HTTPS is required by default. Explicitly enabled plaintext HTTP remains limited to loopback hosts.
+- Redirects are not followed, and credential-bearing requests cannot escape the configured origin or
+  base path.
+- Automatic retry is restricted to the 19 reviewed operations and the statuses `408`, `429`, `502`,
+  `503`, and `504`, plus transport failures. Per-call settings can only tighten the global budget.
+- Requests require identity encoding; compressed responses are rejected before raw bodies are streamed
+  through the byte limit and parsed as JSON.
+- Public errors retain stable status, error code, operation ID, and request ID only; raw response text,
+  query strings, credentials, and underlying exception text are not exposed.
+- Cursor helpers enforce a finite page limit and reject missing or repeated cursors.
+- `provider_profile` and `reply_token` are sensitive outputs. Do not log complete account or message
+  responses.
+
+The package does not expose MCP tools, Agent Skills, a generic raw-request escape hatch, provider-specific
+orchestration, or an inferred webhook-signature algorithm.
+
+## Contract and generated code
+
+`contracts/device.openapi.yaml` is the only protocol source for generation. The language-neutral policy
+file records semantics that cannot be inferred safely from HTTP methods. Do not edit
+`src/unifyport/_generated/` or generated API reference pages directly.
+
+```bash
+python scripts/generate.py
+python scripts/generate.py --check
+python scripts/check_node_parity.py --node-repo ../unifyport-sdk-node --node-ref v0.4.0
+```
+
+See the [API coverage report](https://github.com/Unify-Port/UnifyPort-SDK-Python/blob/main/docs/api-coverage.md),
+[architecture](https://github.com/Unify-Port/UnifyPort-SDK-Python/blob/main/docs/architecture.md),
+[security boundaries](https://github.com/Unify-Port/UnifyPort-SDK-Python/blob/main/docs/security.md),
+[contract maintenance guide](https://github.com/Unify-Port/UnifyPort-SDK-Python/blob/main/docs/contract-maintenance.md),
+[acceptance report](https://github.com/Unify-Port/UnifyPort-SDK-Python/blob/main/docs/acceptance-report.md),
+and [release notes](https://github.com/Unify-Port/UnifyPort-SDK-Python/blob/main/docs/release-notes.md).
+
+## Validation
+
+```bash
+ruff format --check .
+ruff check .
+mypy --strict src scripts typing_tests
+npx --yes pyright@1.1.411 pyright_tests
+pytest
+python -m build
+twine check dist/*
+python scripts/check_public.py dist/*
+python scripts/smoke_installed.py
+pip-audit
+```
+
+## License
+
+The SDK source is available under the
+[MIT License](https://github.com/Unify-Port/UnifyPort-SDK-Python/blob/main/LICENSE). The Device API
+contract describes the service interface and retains its own license metadata.