Salt 开发环境搭建指南基于双虚拟环境Python 3.10 / 3.14的测试与提交工作流【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/saltSaltSaltStack是一个基于 Python 的大规模基础设施自动化与配置管理项目其仓库同时维护着 3006.x、3007.x 等多个旧分支与 master 主线不同分支对 Python 版本和测试框架的要求并不一致。本指南以仓库内 development-setup.md 为核心结合 architecture.md、.pre-commit-config.yaml 与tools/工具链源码系统讲解如何搭建一套可持续用于跑测试、跑工具命令、跑代码质量检查的本地开发环境并给出每一步的命令、参数说明与常见排错方案。为什么需要两个虚拟环境Salt 仓库的 CI 与本地开发流程同时依赖两套 Python 运行时venv310Python 3.10用于在 3006.x、3007.x 等旧分支上运行测试与工具命令。这些分支仍以 Python 3.10 为基准运行时。venv314Python 3.14用于在 master 分支上运行测试以及执行 pre-commit 钩子、代码格式化与 lint 检查。之所以要求两个环境并存是因为 Salt 的依赖锁定体系requirements/static/下的 lock 文件按 Python 版本与平台分别生成旧分支与主线的依赖集合存在差异同时tools/命令工具链、pre-commit 钩子等开发期组件依赖的python-tools-scripts与测试运行依赖也不完全相同。两个环境互不干扰、各司其职避免频繁重建虚拟环境。从仓库结构看requirements/static/pkg 与 requirements/static/ci 分别维护着 py3.9py3.14 多个版本的平台 lock 文件印证了这套按 Python 版本分环境的开发策略。前置条件在开始搭建前请确认系统满足以下条件已安装Python 3.10与Python 3.14系统上同时存在两个解释器安装时可通过python3.10、python3.14命令显式调用已克隆 Salt 仓库到本地即当前仓库根目录网络可访问 PyPI用于下载依赖包如果系统中python3默认指向的版本与预期不符建议在后续所有命令中显式使用python3.10/python3.14文档排错一节也特别强调了这一点。搭建 venv310Python 3.10venv310 专用于 3006.x / 3007.x 分支的测试。在仓库根目录依次执行# 1. 创建虚拟环境 python3.10 -m venv venv310 # 2. 激活 source venv310/bin/activate # 3. 升级打包工具链 pip install --upgrade pip setuptools wheel # 4. 安装平台相关的运行时依赖按操作系统选择其一 # Linux: pip install -r requirements/static/pkg/py3.10/linux.lock # macOS: pip install -r requirements/static/pkg/py3.10/darwin.lock # Windows: pip install -r requirements/static/pkg/py3.10/windows.lock # 5. 安装 pytest 测试依赖 pip install -r requirements/pytest.txt # 6. 以可编辑模式安装 Salt 本体 pip install -e . # 7. 安装 tools 工具链依赖用于 python -m tools 系列命令 pip install -r requirements/static/ci/py3.10/tools.lock # 8. 安装 pre-commit 与 python-tools-scripts pip install pre-commit python-tools-scripts # 9. 退出虚拟环境 deactivate各步骤的作用与要点第 4 步的平台 lock 文件requirements/static/pkg/py3.10/下存放了 Linux、macOS、Windows、FreeBSD 四个平台的锁定依赖linux.lock、darwin.lock、windows.lock、freebsd.lock直接按当前操作系统选择对应文件即可锁定文件保证了与 CI 完全一致的依赖版本。第 5 步requirements/pytest.txt 提供运行测试所需的 pytest 及其插件集合。第 6 步pip install -e .以可编辑模式安装 Salt使本地代码修改即时生效无需重复安装这是 Salt 开发的标准做法。第 7 步requirements/static/ci/py3.10/tools.lock是 CI 侧工具依赖的锁定文件仓库中确实存在该路径它提供了tools/命令运行所需的第三方库详见下文tools 工具链一节。搭建 venv314Python 3.14venv314 专用于 master 分支测试与 pre-commit 代码检查。步骤与 venv310 基本一致额外在最后执行pre-commit install安装 Git 钩子# 1. 创建虚拟环境 python3.14 -m venv venv314 # 2. 激活 source venv314/bin/activate # 3. 升级打包工具链 pip install --upgrade pip setuptools wheel # 4. 安装平台相关运行时依赖按操作系统选择其一 # Linux: pip install -r requirements/static/pkg/py3.14/linux.lock # macOS: pip install -r requirements/static/pkg/py3.14/darwin.lock # Windows: pip install -r requirements/static/pkg/py3.14/windows.lock # 5. 安装 pytest 依赖 pip install -r requirements/pytest.txt # 6. 以可编辑模式安装 Salt pip install -e . # 7. 安装 tools 依赖 pip install -r requirements/static/ci/py3.14/tools.lock # 8. 安装 pre-commit 与 python-tools-scripts pip install pre-commit python-tools-scripts # 9. 安装 pre-commit 钩子将钩子注册到 .git/hooks/ pre-commit install # 10. 退出虚拟环境 deactivatepre-commit install会在 Git 的 hooks 目录中注册钩子此后每次git commit都会自动触发代码质量检查具体检查项见下文pre-commit 钩子一节。两个环境的使用分工搭建完成后两个环境各司其职环境用途venv310在 3006.x / 3007.x 分支上运行测试直接以 pytest 执行旧分支测试运行 tools 命令python -m toolsvenv314在 master 分支上运行测试运行 pre-commit 钩子执行代码格式化与 lint 检查提交前的 pre-commit 校验验证安装是否成功搭建完成后可用以下命令快速验证环境可用性# 验证 Salt 可导入并输出版本master / 默认开发分支 ./venv314/bin/python -c import salt.version; print(salt.version.__version__) # 运行一个单元测试验证测试链路 ./venv314/bin/pytest tests/pytests/unit/loader/test_loader.py -v # 验证 3006.x/3007.x 工作流的 tools 命令 ./venv310/bin/python -m tools --help注意文档示例中的测试路径为tests/pytests/unit/test_loader.py而当前仓库中实际的加载器测试位于 tests/pytests/unit/loader/test_loader.py另有一份功能测试在 tests/pytests/functional/loader/test_loader.py。执行前可先确认具体测试文件路径。关键使用原则始终使用正确的解释器运行测试或工具时要么使用 venv 内可执行文件的完整路径要么先激活对应虚拟环境切勿依赖系统全局的 Python。这是保证依赖完整、版本正确的关键方式一完整路径直接调用./venv310/bin/pytest tests/pytests/unit/test_foo.py -v ./venv314/bin/pre-commit run --files salt/loader/lazy.py ./venv310/bin/python -m tools ts pytest run tests/pytests/unit/方式二先激活再执行source venv314/bin/activate pytest tests/pytests/unit/test_foo.py -v deactivate深入tools 工具链与python -m tools开发文档中多次出现python -m tools形式的命令如python -m tools ts pytest run ...这是 Salt 仓库为开发者提供的统一命令行工具入口。从源码看tools/main.py 直接委托给ptscripts.__main__的main()即工具链建立在ptscriptsPython Tools Scripts框架之上配合python-tools-scripts包文档要求单独安装且.pre-commit-config.yaml中引用了saltstack/python-tools-scripts的固定版本0.20.5。以测试子命令为例tools/testsuite/pytest.py 定义了名为pytest的命令组挂载在父命令ts之下专门提供直接调用 pytest 进行快速本地测试的系列命令其实现会优先从指定 venv 路径venv/bin/pytest解析 pytest 可执行文件再回退到 PATH 查找——这正是文档强调使用 venv 完整路径的底层原因之一。此外 tools/ci.py、tools/changelog.py、tools/docs.py、tools/gh.py、tools/release.py 等模块提供了 CI 流程、变更日志、文档检查、GitHub 交互与发布相关的命令构成了一个完整的开发辅助工具集。深入pre-commit 钩子都检查什么在 venv314 中执行pre-commit install后每次提交都会运行 .pre-commit-config.yaml 中声明的钩子。该配置主要包含三部分1. 通用代码卫生钩子pre-commit/pre-commit-hooks v4.5.0check-merge-conflict检查文件是否包含合并冲突标记trailing-whitespace去除行尾空白mixed-line-ending统一行尾--fixlf统一为 LFend-of-file-fixer确保文件以单个换行结尾check-ast校验 Python 文件能否被 AST 正常解析check-json/check-symlinks/check-case-conflict分别检查 JSON 语法、失效软链接、大小写冲突文件名debug-statements拦截breakpoint()等调试语句fix-encoding-pragma/fix-byte-order-marker清理编码声明与 BOMforbid-submodules禁止引入子模块2. yamllintv1.38.0针对.pre-commit-config.yaml本身检查重复键问题。3. Salt 专属检查saltstack/python-tools-scripts 0.20.5check-changelog-entries校验变更日志条目是否符合规范对应changelog/目录下的*.fixed.md、*.added.md等文件generate-workflows/actionlint生成并检查 GitHub Actions 工作流对应 cicd/shared-gh-workflows-context.yml 模板check-docs检查salt/下 Python 源码与doc/ref/文档的一致性check-docstrings/check-cp1252-docstrings检查 docstring 规范与 Windows 控制台编码兼容性loader-check-virtual校验 loader 模块的__virtual__声明对应架构文档中描述的虚拟模块机制check-filemap校验 tests/filename_map.yml 与测试文件变更的匹配check-lint-locks校验 lint 依赖 lock 文件的一致性此外配置中还通过uv-pre-commit的pip-compile钩子为 py3.9py3.14 各版本、各平台自动生成并校验 requirements/static/pkg 与 requirements/static/ci 下的 lock 文件确保依赖锁定文件与上游约束文件始终同步。如需只对指定文件运行检查例如修改了加载器源码后可执行./venv314/bin/pre-commit run --files salt/loader/lazy.py常见问题排错ModuleNotFoundError: No module named ptscripts运行python -m tools报错No module named ptscripts时说明工具链依赖未安装或环境不对。在对应虚拟环境中补充安装./venv310/bin/pip install -r requirements/static/ci/py3.10/tools.lock ./venv310/bin/pip install python-tools-scriptsmaster 工作流同理改用 venv314 与py3.14/tools.lock。venv 路径不存在No such file or directory确保已经按上文步骤创建了venv310/venv314并且所有命令都在仓库根目录下执行。虚拟环境目录是相对仓库根目录创建的离开该目录后相对路径自然失效。权限或解释器版本错误某些系统上python3可能指向其他版本导致创建出的环境 Python 版本不对。请显式使用python3.10/python3.14命令并在创建前确认python3.10 --version # 期望 3.10.x python3.14 --version # 期望 3.14.xpre-commit 钩子未生效若提交时没有任何检查输出说明钩子尚未注册。进入 venv314 环境执行一次安装即可source venv314/bin/activate pre-commit install deactivate与 Salt 项目结构的衔接理解这套开发环境后可与仓库整体结构对照更快进入开发状态核心源码salt/目录下按职责划分为 salt/modules执行模块、salt/states状态模块、salt/loader插件加载器、salt/transport通信层、salt/utils工具函数等修改后即时通过pip install -e .生效。测试体系tests/pytests 下按unit/单元测试不启守护进程、functional/功能测试无外部依赖、integration/集成测试需要守护进程与网络、scenarios/场景测试、pkg/打包测试分层组织测试支持代码位于 tests/support。分支切换在 3006.x/3007.x 分支上开发时使用 venv310 跑测试与 tools 命令在 master 分支上开发时使用 venv314 跑测试并依靠 venv314 中的 pre-commit 完成提交前检查——这也是文档反复强调始终用正确虚拟环境的根本原因。小结一套符合 Salt 官方开发流程的本地环境 venv310旧分支测试 venv314主线测试与 pre-commit双环境配合平台与版本对应的 lock 文件、可编辑安装的 Salt 本体、ptscripts 驱动的tools/命令链以及 pre-commit 代码质量门禁。按本指南完成搭建后即可在任意分支上稳定地运行单元测试、执行python -m tools系列命令并在提交前自动通过 Salt 专属的文档、docstring、加载器与变更日志等检查。【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/salt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
