exclude docs from wheel; harden bundle item handling; single-source version
This commit is contained in:
ykcheungab
+4
-6
@@ -5,8 +5,6 @@ description: 安装并运行 Orisys SDK 的基础步骤
|
||||
|
||||
# 快速开始
|
||||
|
||||
版本：0.5.2
|
||||
|
||||
## 简介
|
||||
本文件介绍如何上手和运行叠动视触觉传感器配套的开发套件。本套件是配合叠动视触觉传感器进行图像处理，计算形变、力以及接触信息。它可以从摄像头或视频文件中读取图像，处理后打印和展示处理后信息。
|
||||
支持操作系统：Windows、Ubuntu
|
||||
@@ -84,9 +82,9 @@ pip install --upgrade orisys
|
||||
### 使用 .whl 文件安装（离线或指定版本）
|
||||
从官方渠道获取 .whl 文件，文件名格式通常为：
|
||||
orisys-{版本}-{Python版本}-{Python版本}-{操作系统}_{硬件架构}.whl
|
||||
例如：orisys-0.5.2-cp310-cp310-win_amd64.whl 表示：
|
||||
例如 `orisys-<版本>-cp310-cp310-win_amd64.whl` 表示：
|
||||
|
||||
版本：0.5.2
|
||||
版本：`<版本>`（以实际下载的文件名为准，可用 `python -c "import orisys; print(orisys.__version__)"` 确认）
|
||||
Python 版本：3.10（cp310）
|
||||
操作系统：Windows（win）
|
||||
硬件架构：64位（amd64）
|
||||
@@ -97,7 +95,7 @@ Python 版本：3.10（cp310）
|
||||
|
||||
```bash
|
||||
# 请将文件名替换为您实际下载的文件名
|
||||
pip install orisys-0.5.2-cp310-cp310-win_amd64.whl
|
||||
pip install orisys-<版本>-cp310-cp310-win_amd64.whl
|
||||
```
|
||||
|
||||
### 安装 CuPy（可选）
|
||||
@@ -139,7 +137,7 @@ python
|
||||
import orisys
|
||||
print(orisys.__version__)
|
||||
```
|
||||
如果输出版本号（例如 0.5.2），则说明安装成功。
|
||||
如果打印出版本号，则说明安装成功。
|
||||
|
||||
## 使用方法
|
||||
### 运行示例程序
|
||||
|
||||
+49
-9
@@ -46,20 +46,22 @@ python build/run.py wheel-manylinux -PythonVersions 3.10
|
||||
## 2. 发布前门禁：`release preflight`
|
||||
|
||||
```powershell
|
||||
python build/run.py release preflight --version 0.5.2
|
||||
# --version 可省略：默认取 pyproject 的 dynamic version（即 src/orisys/__init__.py 里的 __version__）
|
||||
python build/run.py release preflight
|
||||
```
|
||||
|
||||
按顺序执行 7 个步骤，任一步失败即整体失败（`--keep-going` 可改为收集全部失败）：
|
||||
按顺序执行 8 个步骤，任一步失败即整体失败（`--keep-going` 可改为收集全部失败）：
|
||||
|
||||
| 步骤 | 检查内容 |
|
||||
| --- | --- |
|
||||
| `repo-state` | 是 git 仓库、工作树干净、记录 HEAD（`--allow-dirty` 可豁免，用于提交前预检） |
|
||||
| `version-consistency` | `src/orisys/__init__.py::__version__` == pyproject 的 dynamic attr == `SDK/<version>/` 中 wheel 文件名里的版本 |
|
||||
| `version-strings` | 追踪的文本文件里没有与当前版本不符的版本字面量（见 §5.3） |
|
||||
| `duplicate-guard` | 该版本是否**已经发布过**：本地 git tag（`v<version>` / `<version>`，含 sibling `orisys-sdk-release` 仓库）命中即拒绝；`--check-pypi` 时再查 PyPI。`SDK/<version>/` 里已有 wheel 只作信息展示——那是 preflight 的正常输入，不是错误 |
|
||||
| `tests` | `pytest -m "not slow and not hardware"`（`--longrun` 时包含 slow） |
|
||||
| `bundle-precheck` | 每个 `[[tool.orisys.bundle.items]]` 至少解析出 1 个文件；finger 必需资产存在 |
|
||||
| `wheel-inspection` | 逐个 wheel 做静态断言：文件名/版本/METADATA 字段/RECORD 哈希/压缩包路径/体积上限/无 pyc 与缓存/无 `orisys/**/*.py` 源码泄漏/与源码树逐文件字节一致 |
|
||||
| `wheel-runtime` | 在一次性 venv 中安装该 wheel，断言内置 configs/sensors 资产可加载，并对真实视频跑 40 帧公开流水线（无需相机、无 GUI） |
|
||||
| `wheel-runtime` | 每个 wheel **一个** venv，在里面依次做：导入冒烟 → 内置 configs/sensors 资产可加载 → 对真实视频跑 40 帧公开流水线（无需相机、无 GUI） |
|
||||
|
||||
正常顺序是**先构建、再 preflight**，不需要额外开关：
|
||||
|
||||
@@ -98,10 +100,10 @@ python build/run.py release preflight --all-wheel-pythons --check-pypi
|
||||
对单个 wheel 做静态断言（+ 可选运行时校验），不需要版本上下文。适合体检历史产物：
|
||||
|
||||
```powershell
|
||||
python build/run.py release audit SDK\0.5.2\orisys-0.5.2-cp312-cp312-win_amd64.whl
|
||||
python build/run.py release audit dist\repaired\orisys-0.5.2-cp310-cp310-win_amd64.whl --strict-bundle
|
||||
python build/run.py release audit SDK\<version>\orisys-<version>-cp312-cp312-win_amd64.whl
|
||||
python build/run.py release audit dist\repaired\orisys-<version>-cp310-cp310-win_amd64.whl --strict-bundle
|
||||
|
||||
# 追加运行时校验
|
||||
# 追加运行时校验（--assets 与 --runtime 同时给时共用一个 venv，只装一次依赖）
|
||||
python build/run.py release audit <wheel> --assets --runtime --video data/sample/s1_480p.mp4
|
||||
```
|
||||
|
||||
@@ -129,8 +131,8 @@ python build/run.py verify --gui-dist --product ory_finger
|
||||
4. PyPI：先 TestPyPI 再正式仓库。
|
||||
|
||||
```powershell
|
||||
python -m twine upload --repository testpypi SDK/0.5.2/*.whl
|
||||
python -m twine upload SDK/0.5.2/*.whl
|
||||
python -m twine upload --repository testpypi SDK/<version>/*.whl
|
||||
python -m twine upload SDK/<version>/*.whl
|
||||
```
|
||||
|
||||
**不要把 API token 写进仓库**。`release preflight --check-pypi` 只做只读查询，不需要 token。
|
||||
@@ -163,7 +165,7 @@ python -m twine upload SDK/0.5.2/*.whl
|
||||
|
||||
---
|
||||
|
||||
## 5. 两个必须记住的坑
|
||||
## 5. 三个必须记住的坑
|
||||
|
||||
### 5.1 Nuitka 编译包的 `__file__` 是假的
|
||||
|
||||
@@ -194,3 +196,41 @@ root = distribution("orisys").locate_file("orisys") # site-packages/orisys
|
||||
|
||||
处置：在构建环境里执行 `pip uninstall -y orisys`，或改用不带 `--offline` 的完全隔离 venv（会联网安装依赖）。
|
||||
|
||||
### 5.3 版本号只有一个地方，其他都是推导出来的
|
||||
|
||||
版本号的唯一来源是 **`src/orisys/__init__.py::__version__`**。以下全部由它推导，不需要手改：
|
||||
|
||||
| 产物 | 推导方式 |
|
||||
| --- | --- |
|
||||
| pyproject 的 `[project] version` | `[tool.setuptools.dynamic] version = {attr = "orisys.__version__"}` |
|
||||
| wheel 文件名里的版本 | `build/wheel/build.py` 调 `get_version()` |
|
||||
| wheel `METADATA` 的 `Version:` | 生成的 `setup.py` 里写入同一个 `version` |
|
||||
| `SDK/<version>/` 目录名 | 同上 |
|
||||
| `importlib.metadata.version("orisys")` | 从 wheel METADATA 读出 |
|
||||
|
||||
因此**不要**再往文档、示例、测试里写具体版本号：
|
||||
|
||||
- 用法示例写 `SDK/<version>/...`、`--version <version>`，不要写具体版本
|
||||
- 文档里不要写「版本：x.y.z」；需要时让用户用 `python -c "import orisys; print(orisys.__version__)"` 自己看
|
||||
- 示例脚本的 docstring 不要再写 `SDK version: x.y.z`
|
||||
- 测试里需要「一个版本」时用明显是假的版本号（如 `1.x.y` 这种不会与真实版本混淆的值），不要用当前版本 —— 否则每次发版都要改测试，而且一次全局替换就会悄悄改坏断言
|
||||
|
||||
`release preflight` 的 `version-strings` 步骤强制这条规则：扫描所有被追踪的文本文件，任何与当前版本不符的版本字面量都会导致失败（`tests/` 与生成物除外；依赖约束如 `numpy>=1.24.4` 由正则排除）。
|
||||
|
||||
历史记录属于例外，需显式登记在 `build/release/version.py::VERSION_STRING_ALLOWLIST` 里——登记本身就是「该字面量故意不是包版本」的文档。**不要用全局替换修改含历史版本的文件**：本文件的发布记录表就曾被一次全局替换改错（`0.50` typo tag 被挂到错误的版本上，`0.5.1` 那一行被覆盖丢失）。
|
||||
|
||||
### 5.4 wheel 里有什么、没有什么
|
||||
|
||||
打包内容由 `pyproject.toml` 的 `[[tool.orisys.bundle.items]]` 单点定义：
|
||||
|
||||
| 内容 | 是否进 wheel | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `config/*.json` | 是 | `orisys/configs/`，运行时配置解析要用 |
|
||||
| `sensors/**` | 是 | `orisys/sensors/`，含 finger 的 npz/npy 资产，运行时与 GUI 都要用 |
|
||||
| `examples/**` | 是 | `orisys/examples/`，用户装完就能跑示例 |
|
||||
| `docs/**` | **否** | 只随 GitHub 仓库与 PyPI 项目页提供。`docs/publishing.md` 是内部流程文档；`docs/pypi_readme.md` 仅在构建时被读取作为 long description |
|
||||
|
||||
因为 docs 不进 wheel，**改文档不会让已构建的 wheel 失效**，不需要重新构建。（改 `examples/`、`config/`、`sensors/` 会——它们确实在 wheel 里，`wheel-inspection` 的 `bundle-fidelity` 会报出来。）
|
||||
|
||||
如果以后需要离线 API 参考，加一个只包含 `docs/api.md` 的窄条目即可，不要整个 `docs/` 都塞进去。
|
||||
|
||||
|
||||
+1
-1
@@ -2,7 +2,7 @@
|
||||
|
||||
叠动科技视触觉传感器配套的 Python SDK，提供图像采集、拼接、稠密光流、Helmholtz-Hodge 分解、接触与深度估计，以及可运行的示例。
|
||||
|
||||
本文件是 PyPI 项目描述（`long_description`）的源文件。它按构建配置 `PYPI_README_RELPATH` 打包进 wheel，因此**不要**在这里写内部仓库布局、构建流水线或发布步骤——那些内容属于仓库内的 `README.md` 与 `docs/publishing.md`。
|
||||
本文件是 PyPI 项目描述（`long_description`）的源文件：构建时由 `docs/publishing.md` 所述流程从**检出目录**读取（`build/wheel/package.py::PYPI_README_RELPATH`），**不会**被打进 wheel。因此不要在这里写内部仓库布局、构建流水线或发布步骤——那些内容属于仓库内的 `README.md` 与 `docs/publishing.md`。
|
||||
|
||||
```bash
|
||||
python -m pip install orisys
|
||||
|
||||
Reference in New Issue
Block a user