FreeCAD 如何重新生成 Python 绑定 stub 并构建发布 freecad-typings 包【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCAD如果你的工作目录里有 FreeCAD 源码并且绑定代码PyCXX 包装、.pyi签名文件刚发生过变动你需要让随源码分发的类型 stub 跟上新 API把 stub 打成freecad-typings包发上 PyPI让下游的静态类型检查器Pyright、Pyrefly、MyPy能用上新签名。FreeCAD 在src/Tools/typing/下提供了一条完整的生成—检查—打包—发布流水线入口脚本是 generate_stubs.py实现位于src/Tools/typing/stubgen/包中打包清单模板在 PYPROJECT_TEMPLATE.toml。所有命令都从 FreeCAD 仓库根目录执行generated/是纯本地的一次性输出仓库只保留generated/.gitignore重新生成前无需清理。前提条件一份完整的 FreeCAD 源码检出命令在仓库根目录运行--root .指的就是它。python3驱动generate_stubs.py生成器与 lint。uvREADME 明确说明构建和发布步骤用uv完成uv publish前需要设置UV_PUBLISH_TOKEN或先登录 PyPI。生成器本身不需要启动 FreeCAD 或编译 Cstubgen是纯源码解析管线从绑定包装源码、*.module.pyi文件和 curated 输入中推导 API 面。重新生成 stub 并跑冒烟检查最短主路径是执行辅助脚本 check-stubs.sh它内部等价于运行check模式python3 src/Tools/typing/generate_stubs.py check \ --root . \ --out-dir src/Tools/typing/generated这条命令依次做三件事见 check-stubs.sh 与 README 说明先跑stubgen的聚焦单元测试包括结构化 property-contract 目录检查生成一次性 stub 树到src/Tools/typing/generated/把 Pyright 和 Pyrefly 指向冒烟检查目标做静态类型检查。生成的输出有三类generated/stubs/叠加overlay已应用的、按导入形态组织的公开 stub 树可直接作为类型检查器的 search path也是冒烟检查使用的输出generated/stubs/Module/py.typed写入每个顶层模块目录的 PEP 561 标记让类型检查器在包安装后仍能发现 stubgenerated/pyproject.tomlfreecad-typings的打包清单使用hatchling构建后端版本号取自仓库根目录的version.json并把stubs/树复制到 wheel 根使顶层模块可直接导入如import FreeCAD。冒烟检查是如何验证的check模式的两个类型检查器都指向 smoke/smoke.pypyrightconfig.json 把extraPaths设为../generated/stubspyrefly.toml 把search-path设为同一目录。smoke.py是一个刻意密集导入、密集调用的文件覆盖FreeCAD、FreeCADGui、Part、Sketcher、Materials等公开模块的assert_type/reveal_type断言。注意这个文件从不会被执行它只供静态检查器遍历生成的 stub当某个符号移动、消失或签名变得不兼容时报错。判断依据脚本退出码。CI 侧的 tools/lint/python_stubs.py 就是包装了同一条check命令额外传入--log-dir并以退出码决定在 Markdown 报告里写 Generated binding stub smoke checks passed 还是 failed。所以本地运行check-stubs.sh返回 0就等价于生成器单元测试、stub 生成、Pyright、Pyrefly 四项全过。审计手写 stub 文档可选如果你还维护了 source-adjacent 的.pyi文件可以用文档 lint 检查它们的 docstring 覆盖情况python3 src/Tools/typing/generate_stubs.py lint-docs --root .它只检查 curated 源文件要求模块 docstring以及 curated 顶层函数、类和其方法的 docstring不检查整个生成的公开 stub 树。文档覆盖还在补齐阶段时可以在lint-docs后追加具体文件或目录路径来审计更小范围。构建 freecad-typings 包生成完成后进入generated目录构建cd src/Tools/typing/generated uv build # 产出 dist/freecad_typings-version.tar.gz 和 .whl其中version即version.json中的 FreeCAD 版本文件名中的版本号随当前仓库状态而定不是固定值。构建产物落在generated/dist/。打包行为的来源PYPROJECT_TEMPLATE.toml 声明name freecad-typings、requires-python 3.11sdist 只包含stubs/**、pyproject.toml、README.mdignore-vcs truewheel 侧用force-include { stubs . }把 stub 树铺到 wheel 根保证import FreeCAD这类顶层导入在安装后成立。发布到 PyPI构建成功后发布uv publish这是有副作用的一步它会把dist/里的包上传到 PyPI。前提是设置UV_PUBLISH_TOKEN环境变量或已先登录且账号对freecad-typings项目有发布权限。要发布候选版本或开发快照时文档给出的替代方式是传显式的 index URL例如发到 Test PyPIuv publish --publish-url https://test.pypi.org/legacy/限制与维护约定发布前必须重新生成。README 明确要求凡是绑定发生了变化就要在发布前重新运行生成让 wheel 反映当前 API。不要手改生成输出。generated/stubs/是一次性本地输出要修正签名编辑 curated 源输入source-adjacent.pyi、*.module.pyi、src/Tools/typing/inputs/overlays/下的 overlay然后重新生成。overlay 保持最小化。公开模块 overlay 只合并顶层符号别名、辅助类型、生成器尚不能建模的手写 API且路径要镜像公开导入树如inputs/overlays/PySide/QtCore.pyiPivy 等第三方包在 stub 准备好之前不进入该树。CI 集成点固定。仓库的 lint 入口 tools/lint/python_stubs.py 必须传入--log-dir与--report-file它运行的是与本文章相同的check命令并把三个日志段stub 生成、Pyright、Pyrefly追加进 Markdown 报告如果你要复用或排查 CI 结果按这个参数约定执行。完成到发布为止的闭环是check-stubs.sh全绿 →uv build出 sdist/wheel →uv publish上传。发布后下游项目安装freecad-typings即可在requires-python 3.11的环境中获得带py.typed标记的 FreeCAD Python API 类型面。【免费下载链接】FreeCADOfficial source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeCAD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考