Home Assistant 开发环境如何用 script/lint 与 script/check_format 检查并提交代码【免费下载链接】core:house_with_garden: Open source home automation that puts local control and privacy first.项目地址: https://gitcode.com/GitHub_Trending/co/core你修改了 Home Assistant core 仓库里的 Python 代码想确认改动满足项目的格式与 lint 标准后再提交、发 PR。这个仓库在script/目录下提供了固定的开发检查入口script/check_format 检查代码格式script/lint 对相对上游dev分支改动的文件跑 lint配合 AGENTS.md 与 CONTRIBUTING.md 中的提交规范即可完成“本地检查 → 提交 → 发起 PR”的完整流程。本文只覆盖这条路径不涉及功能开发本身。准备用 script/setup 搭建开发环境仓库要求 Python 3.14根目录 .python-version 固定为3.14.5并使用uv管理虚拟环境。AGENTS.md 明确要求进入新的环境或 worktree 时先运行script/setup这是提交代码前的必要步骤。script/setupscript/setup 脚本按顺序做以下几件事中途出错即停止若.vscode/settings.json不存在从.vscode/settings.default.jsonc复制一份创建config/目录若当前没有激活的虚拟环境VIRTUAL_ENV为空优先用uv venv .venv创建否则回退到python3 -m venv .venv然后激活.venv若系统没有uv用python3 -m pip install uv安装执行 script/bootstrap安装开发依赖uv pip install -e . -r requirements_all.txt -r requirements_test.txt colorlog并把全部英文翻译编译到翻译目录执行prek install安装 pre-commit 钩子prek即 pre-commit 的入口运行hass --script ensure_config -c config生成配置并在config/configuration.yaml中缺少 logger 配置时追加一段logger配置块。已知问题如果uv报告找不到所需的 Python 版本说明你的 uv 版本过旧。AGENTS.md 给出的处理方式是先升级 uv 再重跑 setupcurl -LsSf https://astral.sh/uv/install.sh | sh script/setup检查代码格式script/check_format格式检查入口是 script/check_format它固定检查仓库内的四个位置script/check_format脚本内部执行的是ruff format --check --quiet homeassistant tests script *.py注意两点--check表示只检查不修改所以它不会改动你的文件--quiet表示格式全部通过时基本无输出有不符合格式的文件时才会列出文件名。因此判断方式很简单无输出即通过列出文件即需要重新格式化。需要修复格式时不必手工逐文件处理仓库的 .pre-commit-config.yaml 注册了ruff-format钩子以及带--fix参数的ruff-check钩子提交时会自动修正格式问题。也可以等提交阶段由钩子统一处理但建议提交前再跑一次script/check_format确认干净。对改动文件运行 lintscript/lintscript/lint 只检查“你这次改动的 Python 文件”而不是整个仓库。它先执行git diff $(git merge-base upstream/dev HEAD)取出改动文件列表因此有两个前置条件本地必须配置名为upstream的远端且分支基于upstream/dev改动必须已经git add并git commit——未提交的改动不在 diff 结果里脚本会直接打印No python file changed.退出。script/lint脚本按两步输出结果先打印FILES CHANGED区块列出参与检查的.py文件再打印LINT with ruff区块对这些文件执行prek run ruff-check --files ...最后打印LINT with pylint区块对其中非测试文件执行pylint。如果改动只有tests/下的文件脚本打印Only test files changed. Skipping并退出——这与 script/lint_and_test.py 中的注释一致tests/* does not have to pass lint。任一步报错都会出现在对应区块下按文件与行号修改后重跑即可。提交前的完整钩子检查可选如果你希望比script/lint覆盖更多检查项ruff 修复与格式化、codespell 拼写检查、yamllint、prettier、mypy、pylint、gen_requirements_all、hassfest 等AGENTS.md 建议在一次代码会话结束后运行uv run --no-sync prek run --all-filesVS Code 用户也可以使用 .vscode/tasks.json 里预置的任务其中Prek任务执行的正是prek run --show-diff-on-failureRuff任务执行prek run ruff-check --all-files失败时会显示 diff 便于定位。快速自查 PR 标准可选script/lint_and_test.py 用于“快速检查分支是否达到 PR 标准”它明确说明自己不是完整 CI 的替代只是开发期间的快速检查。它同样基于upstream/dev的 merge-base 找出改动文件要求改动已提交否则提示No changed files found. Please ensure you have added your changes with git add git commit然后依次执行对改动的.py文件跑 pylint 与 ruff有错误时输出Please fix your lint issues before continuing并停止若改动了homeassistant/components/下的文件额外校验gen_requirements_all是否通过不通过时提示Please run script/gen_requirements.py按文件名映射规则找出对应的tests/测试文件并运行 pytest。python3 script/lint_and_test.py判断标准看结尾输出全部通过时打印Yay! This will most likely pass CI文档原文如此表示“很可能”通过 CI不是保证测试失败则打印Tests not passing。带--skiplint参数可跳过 lint 步骤输出中会标注LINT DISABLED仅适合确认 lint 已通过后快速复跑测试。提交与发起 PR检查全部通过后按仓库规范提交并发起 PR分支限制pre-commit 配置中的no-commit-to-branch钩子禁止直接向dev、master、rc分支提交改动必须走 PR提交历史AGENTS.md 要求不要在 PR 分支已经推送的提交上做amend、squash 或 rebase因为评审者需要按提交历史跟踪每次审查后的变化PR 流程CONTRIBUTING.md 说明 PR 要针对dev分支发起并确保测试通过AGENTS.md 要求使用仓库的 PR 模板不得删除模板中任何内容未勾选的复选框也要保留原样。限制说明script/lint与script/lint_and_test.py都依赖upstream/dev作为对比基线若你的分支不是从upstream/dev切出取到的改动文件列表会不符合预期script/lint_and_test.py只是快速自检AGENTS.md 中提到的钩子检查如prek run --all-files与完整 CI 的检查范围不同本地全绿不等于 CI 必然通过格式检查script/check_format与 ruff-format 钩子都只作用于homeassistant、tests、script、*.py等 Python 文件非 Python 文件的格式由 yamllint、prettier 等钩子在 pre-commit 阶段处理。【免费下载链接】core:house_with_garden: Open source home automation that puts local control and privacy first.项目地址: https://gitcode.com/GitHub_Trending/co/core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考