企业官网建设流程全解析

如何把 Poetry 的 poetry-check 与 poetry-lock 接入 pre-commit 钩子？

【免费下载链接】poetryPython packaging and dependency management made easy项目地址: https://gitcode.com/GitHub_Trending/po/poetry

如果你维护一个使用 Poetry 管理依赖的项目，会面临两类提交风险：pyproject.toml被改坏却照样入库，以及依赖变了但poetry.lock没有同步更新。Poetry 官方提供了 pre-commit 钩子（见 docs/pre-commit-hooks.md），可以把poetry check和poetry lock挂到 git 的 pre-commit 阶段，让这两件事在每次提交时自动执行。前提是你的项目已能正常跑 Poetry（Poetry 要求 Python 3.10+，见 docs/_index.md），并且环境中已安装 pre-commit 框架本身（其安装方式以 pre-commit 官方文档为准，Poetry 文档只引用了该框架）。

两个钩子各自做什么

Poetry 文档列出了四个可用的钩子（poetry-check、poetry-lock、poetry-export、poetry-install），本文只接入前两个：

• poetry-check调用poetry check命令，确保 poetry 配置不会以损坏状态被提交。poetry check校验pyproject.toml的内容及其与poetry.lock的一致性，发现错误时会返回详细的报告（见 docs/cli.md 的 check 小节）。该命令支持两个选项：--lock（校验当前pyproject.toml对应存在poetry.lock）和--strict（出现警告时也让检查失败）。
• poetry-lock调用poetry lock命令，确保提交时锁文件是最新的。poetry lock只做锁定、不安装依赖；默认情况下已经写入锁文件的包不会被更新，选项--regenerate则会忽略现有锁文件并从零重建。

两个钩子都接受与对应 poetry 命令相同的参数，且有一条文档明确强调的规则：一旦你在.pre-commit-config.yaml里为某个钩子写了args:，默认参数就被整体覆盖，必须把所有参数完整写出来。

编写 .pre-commit-config.yaml

在仓库根目录创建.pre-commit-config.yaml，最小配置如下（取自文档示例，只保留本文需要的两个钩子）：

repos: - repo: https://github.com/python-poetry/poetry rev: '' # add version here hooks: - id: poetry-check - id: poetry-lock

说明：

• repo字段是钩子来源的仓库地址，属于配置值，必须原样保留。
• rev行文档中给的就是空值加注释# add version here，即你需要填入一个 Poetry 的版本 tag；文档在后面的 pre-commit-update 示例中给出的具体值是1.8.3，可作格式参考。
• 文档原始的最小示例还包含poetry-export和poetry-install两个钩子，此处省略：poetry-export由 Export 插件提供（Poetry 2.0 起不再默认安装该插件），poetry-install的安装方式也不同（需要default_install_hook_types或pre-commit install --install-hooks -t post-checkout -t post-merge），不属于本文的两个钩子。

如果希望钩子更严格，可以给poetry-check传--strict。由于写了args:就会覆盖默认参数，而poetry check本身没有其他必传参数，因此只需写这一个选项：

repos: - repo: https://github.com/python-poetry/poetry rev: '' # add version here hooks: - id: poetry-check args: ["--strict"] - id: poetry-lock

安装钩子并验证

Poetry 仓库的贡献文档（docs/contributing.md）展示了 pre-commit 的对应用法，可照此操作：

# 一次性安装 git 钩子 poetry run pre-commit install # 手动对全部文件跑一遍（默认钩子只检查有改动的文件） poetry run pre-commit run --all-files

pre-commit install之后，每次git commit时钩子都会运行。判断依据来自文档对两个钩子的描述：

• poetry check出错时会输出详细报告，所以如果pre-commit run --all-files中 poetry-check 报错，按报告里的条目修正pyproject.toml即可；没有报告则说明配置校验通过。
• poetry-lock 钩子在提交时执行poetry lock，运行后poetry.lock与pyproject.toml保持一致；如果锁文件内容有变化，把更新后的poetry.lock一并提交。

也可以先手动执行poetry check单独确认基线行为，再交给钩子做提交时兜底。

pyproject.toml 不在仓库根目录时

对于 monorepo 布局或pyproject.toml位于子目录的项目，文档给出的做法是给每个钩子加args: ["-C", "./subdirectory"]（-C即--directory全局选项，指定 Poetry 命令的工作目录）。./subdirectory需替换为你的pyproject.toml实际所在子目录：

repos: - repo: https://github.com/python-poetry/poetry rev: '' # add version here hooks: - id: poetry-check args: ["-C", "./subdirectory"] - id: poetry-lock args: ["-C", "./subdirectory"]

更新 rev：pre-commit autoupdate 的已知限制

文档 FAQ 明确指出，pre-commit autoupdate对这里描述的钩子不可用：它会把每个仓库的rev更新为默认分支上的最新 tag，而 Poetry 的默认分支是活跃开发分支，新 tag 打在稳定分支上，pre-commit 不支持指定分支查找 tag。文档给出的两条出路：

• 用--repo参数显式列出要更新的仓库（可多次指定），避免rev被改成意外的值。
• 可选分支：加入pre-commit-update钩子，它在每次钩子运行时检查并更新仓库配置。文档示例如下（其中rev: 1.8.3与v0.5.1post1均为文档给出的具体值；原示例还包含 poetry-export 与 poetry-install，此处按本文范围省略）：

repos: - repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update rev: v0.5.1post1 hooks: - id: pre-commit-update - repo: https://github.com/python-poetry/poetry rev: 1.8.3 hooks: - id: poetry-check - id: poetry-lock

完成以上配置后，钩子的日常行为就是：提交时自动跑poetry check与poetry lock，配置损坏会被报告拦截，锁文件不一致会被自动刷新。更多钩子参数细节可回到 docs/pre-commit-hooks.md 与 docs/cli.md 的 check、lock 小节核对。

【免费下载链接】poetryPython packaging and dependency management made easy项目地址: https://gitcode.com/GitHub_Trending/po/poetry