pip-deepfreeze

为Python应用程序开发者提供简单的pip freeze工作流程。

目录

• 关于
• 安装
• 快速开始
• 如何使用
• 常见问题解答
• CLI参考
• 其他工具
• 开发
• 贡献

关于

pip-deepfreeze旨在做好一件事情，那就是在虚拟环境中管理Python 应用程序 的依赖关系。

这包括

• 以可编辑模式安装项目及其依赖项，
• 随着项目的发展更新环境中的新依赖项，
• 卸载未使用的依赖项，
• 刷新依赖项，
• 在requirements.txt锁文件中维护固定依赖项，
• 在requirements-{extra}.txt锁文件中维护固定可选依赖项，
• 以树状结构显示已安装依赖项。

本项目的几个特点

• 易于使用，只需执行单个 pip-df sync 命令。
• 速度快，在常规的 pip install + pip freeze 上几乎没有额外开销。
• 它依赖于文档化的 pip 命令行接口和其无处不在的 requirements 文件格式。
• 它假定您的项目使用 PEP 517/660 兼容的构建后端进行配置，但对此后端的具体使用不做假设。
• 它支持将依赖项指定为 VCS 引用。
• 它用 Python 3.8+ 编写，但可以在安装了 pip 的任何虚拟环境中运行，包括 Python 2 和 Python 3.6 及 3.7。
• 它与使用 python3 -m venv --without-pip 创建的没有 pip 的虚拟环境兼容。
• 它相对较小且简单，具有良好的测试覆盖率，并希望易于维护。

安装

使用 pipx（推荐）

pipx install pip-deepfreeze

使用 pip

pip install --user pip-deepfreeze

[!IMPORTANT] 不建议在您的应用程序的相同环境中安装 pip-deepfreeze，以免其依赖项干扰您的应用程序。默认情况下，它与在您的 PATH 中找到的 py 或 python 可执行文件一起工作（在激活的虚拟环境中通常期望这样做），但您可以使用 --python 选项要求它在另一个环境中工作。

快速入门

确保您的应用程序在 pyproject.toml 中声明其直接依赖项，或使用您的 PEP 517/660 兼容的构建后端支持的其他任何机制。

使用您喜欢的工具创建并激活一个虚拟环境。

[!TIP] 当您安装 pip-deepfreeze 时，它也会安装 pip，因此您不需要在您的虚拟环境中单独安装 pip（例如，您可以使用 python3 -m venv --without-pip 来创建它）。但是，如果您的虚拟环境使用的 Python 版本不支持 pip-deepfreeze 的捆绑版 pip，您将需要在目标虚拟环境中安装 pip。

[!IMPORTANT] 当使用小于 23.1 的 pip 时，您可能还需要在虚拟环境中安装 setuptools 和 wheel 以获得最佳效果。

要将在活动的虚拟环境中安装您的项目为可编辑模式，请转到您的项目根目录并运行

pip-df sync

如果您还没有，这将生成一个名为 requirements.txt 的文件，其中包含所有应用程序依赖项的确切版本，就像它们被安装时一样。

然后，您可以将此 requirement.txt 添加到版本控制中，其他参与项目的人可以使用 pip-df sync（或在新的虚拟环境中使用 pip install -r requirements.txt -e .）安装项目和已知的良好依赖项。

[!TIP] pip-deepfreeze 对 uv pip 安装程序有实验性支持。要使用它，请运行 pip-df sync --installer=uvpip。

当您添加或删除项目的依赖项时，再次运行 pip-df sync 以更新您的环境和 requirements.txt。

要更新一个或多个依赖项到允许的最新版本，请运行

pip-df sync --update DEPENDENCY1,DEPENDENCY2 ...

如果您需要从 VCS 引用添加一些依赖项（例如，当一个具有您需要的补丁的库没有在软件包索引中作为发布版提供时），请按常规在项目中添加依赖项，然后将 VCS 引用添加到名为 constraints.txt 的文件中，如下所示

DEPENDENCYNAME @ git+https://g.c/org/project@branch

然后运行pip-df sync。它将使用VCS引用更新requirements.txt，并将引用固定在安装的精确提交上（你需要pip版本20.1或更高版本才能使此功能正常工作）。如果以后你需要更新到同一分支的HEAD，只需使用pip-df sync --update DEPENDENCYNAME。

当你的分支再次合并到上游并且项目已发布版本时，从constraints.txt中删除该行，然后运行pip-df sync --update DEPENDENCYNAME以更新到最新发布的版本。

如何使用

创建新项目。

遵循你喜欢的PEP 517/660兼容构建工具的说明，例如hatch、setuptools、flit或其他工具。在声明第一个依赖项后，创建并激活一个虚拟环境，然后在项目目录中运行pip-df sync以在requirements.txt中生成固定的依赖项。

安装现有项目。

从源代码控制检出项目后，创建并激活虚拟环境，然后运行pip-df sync以安装项目。

更新到项目的最新版本。

当其他人将依赖项添加到项目中后，更新源代码，然后在激活的虚拟环境中运行pip-df sync以将其带到所需的状态：根据需要更新、删除或卸载依赖项。

添加或删除依赖项。

在你向构建工具配置中添加或删除依赖项后，只需运行pip-df sync即可更新你的虚拟环境。你将收到提示以卸载不必要的依赖项。

刷新一些固定的依赖项。

过了一段时间后，你可能想要将一些或所有依赖项刷新到最新版本。你可以使用pip-df sync --update dep1,dep2,...来做到这一点。

刷新所有固定的依赖项。

要更新所有依赖项到最新允许的版本，你可以使用pip-df sync --update-all。这相当于删除requirements.txt然后运行pip-df sync。这也大致相当于在一个空的虚拟环境中重新安装，使用pip install -e . -c constraints.txt然后运行pip freeze > requirements.txt。

使用比PyPI不同的包索引。

在你的项目根目录中创建一个名为constraints.txt的文件，并向其中添加pip选项，例如--index-url或--find-links。你可以添加pip在要求文件中支持的所有选项。

从VCS安装依赖项。

当你直接或间接依赖项中的一个存在错误或缺失功能时，进行上游拉取请求然后从中安装是方便的。例如，假设你的项目依赖于packaging库，并且你想要安装你向它提交的拉取请求。为此，确保将packaging声明为项目的常规依赖项。然后在constraints.txt中添加VCS引用如下

packaging @ git+https://github.com/you/packaging@your-branch

然后运行pip-df sync --update packaging以从分支安装并固定requirements.txt中的精确提交以实现可重复性。当上游合并你的PR并发布版本时，你可以简单地从constraints.txt中删除该行，然后运行pip-df sync --update packaging以刷新到最新发布的版本。

使用额外依赖项。

假设你的项目配置声明了额外的依赖项，如tests或docs，你可以运行pip-df sync --extras tests,docs以更新你的虚拟环境并带有必要的依赖项。这也会将额外的依赖项固定在requirements-tests.txt和requirements-docs.txt中。请注意，pip-deepfreeze假定使用extras机制来指定项目的基依赖项的附加依赖项。

常见问题解答

我应该把什么放在constraints.txt中？我应该添加所有的依赖项吗？

constraints.txt 是可选的。您项目的依赖项主要应在 pyproject.toml（或传统的 setup.py/setup.cfg）中声明。如果需要，constraints.txt 可以包含额外的约束，例如对您无法控制的间接依赖项的版本约束，或者需要从 VCS 源安装的依赖项的 VCS 链接。

我在 constraints.txt 中添加了约束，但 pip-df sync 不尊重它。这是怎么回事？

pip-df sync 总是优先考虑 requirements.txt 中固定的版本，除非明确要求否则。在添加或更改已固定要求的约束或 VCS 引用后，请使用以下方式使用 --update 选项

pip-df sync --update DEPENDENCY1,DEPENDENCY2,...

pip-deepfreez 错误地抱怨 Python 不在虚拟环境中运行。

最可能的原因是您使用了较旧的 virtualenv 版本，它不会生成符合 PEP 405 的虚拟环境。20 及以后的 virtualenv 版本以及 Python 3 的原生 venv 模块都受支持。如果这个问题在实践中很普遍，我们可能会添加对旧版 virtualenv 版本的支持，或者添加一个选项来忽略虚拟环境健全性检查（这只是为了防止 pip-deepfreeze 错误地损坏系统 Python 软件包）。

我如何将选项传递给 pip？

将选项添加到 constraints.txt 是向 pip 传递选项最可靠和最可重复的方法。pip 文档列出了 允许在需求文件中使用的选项。全局选项也可以在 pip 配置文件中设置或通过 PIP_* 环境变量传递（有关更多信息，请参阅 pip 文档）。

为什么不手动使用 pip install 和 pip freeze？

pip-df sync 将这两个命令组合在一起，并确保您的环境和固定要求保持正确和最新。它所促进的一些易于出错的操作包括：卸载不必要的依赖项、更新所选依赖项、使用 VCS 引用覆盖依赖项等。

有没有推荐的方法将我的项目部署到生产环境？

有许多可能性。一种工作得很好（并且在 pip 文档中推荐）的方法包括两个简单的步骤。首先，使用以下方式为您项目和依赖项构建 wheel 文件

pip wheel --no-deps -r requirements.txt -e . --wheel-dir=./wheel-dir

然后，将 wheel-dir 目录的内容发送到您的目标环境或 Docker 映像，并运行

pip install --no-index --find-links=./wheel-dir project-name

请注意，在构建时使用 --no-deps，在安装时使用 --no-index。这将确保所有必需的依赖项都有效地固定在 requirements.txt 中。

CLI 参考

[!NOTE] 命令行界面是唯一受支持的公共接口。如果您发现自己正在编写 import pip_deepfreeze，请不要这样做，因为所有内容都可能随时更改。或者，更确切地说，与您联系以讨论您的需求。

全局选项

Usage: pip-df [OPTIONS] COMMAND [ARGS]...

A simple pip freeze workflow for Python application developers.

Options:
  -p, --python, --py PYTHON     The python executable to use. Determines the
                                python environment to work on. Defaults to the
                                'py' or 'python' executable found in PATH.
  -r, --project-root DIRECTORY  The project root directory.  [default: .]
  --min-version      VERSION    Minimum version of pip-deepfreeze required.
  --version                     Show the version and exit.
  -v, --verbose
  --install-completion          Install completion for the current shell.
  --show-completion             Show completion for the current shell, to copy
                                it or customize the installation.
  --help                        Show this message and exit.

Commands:
  sync  Install/update the environment to match the project requirements.
  tree  Print the installed dependencies of the project as a tree.

pip-df sync

Usage: pip-df sync [OPTIONS]

  Install/update the environment to match the project requirements, and lock new
  dependencies.

  Install/reinstall the project. Install/update dependencies to the latest
  allowed version according to pinned dependencies in requirements.txt or
  constraints in constraints.txt. On demand update of dependencies to to
  the latest version that matches constraints. Optionally uninstall unneeded
  dependencies.

Options:
  -u, --update DEP1,DEP2,...      Make sure selected dependencies are upgraded
                                  (or downgraded) to the latest allowed
                                  version. If DEP is not part of your
                                  application dependencies anymore, this
                                  option has no effect.

  --update-all                    Upgrade (or downgrade) all dependencies of
                                  your application to the latest allowed
                                  version.

  -x, --extras EXTRA1,EXTRA2,... Comma separated list of extras to install
                                  and freeze to requirements-{EXTRA}.txt.

  --post-sync-command TEXT        Command to run after the sync operation is
                                  complete. Can be specified multiple times.

  --uninstall-unneeded / --no-uninstall-unneeded
                                  Uninstall distributions that are not
                                  dependencies of the project. If not
                                  specified, ask confirmation.

  --installer [pip|uvpip]

  --help                          Show this message and exit.

pip-df tree

Usage: pip-df tree [OPTIONS]

  Print the installed dependencies of the project as a tree.

Options:
  -x, --extras EXTRA1,EXTRA2,...  Extras of project to consider when looking for
                                  dependencies.

  --help                          Show this message and exit.

配置

大多数选项都可以从您的 pyproject.toml 文件中的 [tool.pip-deepfreeze] 部分获取默认值。例如

• sync.extras：命令 sync 的 --extras 选项的默认值。
• sync.post_sync_commands：命令 sync 的 --post-sync-command 选项的默认值（作为字符串列表）。
• sync.installer
• min_version

示例

[tool.pip-deepfreeze]
min_version = "2.0"

[tool.pip-deepfreeze.sync]
extras = "test,doc"
post_sync_commands = ["pip-preserve-requirements requirements*.txt"]
installer = "uvpip"

其他工具

存在许多与其他工具具有类似或重叠范围的工具，如 pip-deepfreeze。

• pip 本身。pip-deepfreeze 广泛依赖于 pip CLI 进行安装和查询已安装的分发数据库。本质上它是对 pip install 和 pip freeze 的薄包装。这里的一些功能可能可以为未来 pip 的进化提供灵感。
• pip-tools。这是功能最相似的。除了上文关于中解释的原因外，我还想看看是否只使用pip CLI就能做这样的事情。pip-deepfreeze也比pip-tools和pipdeptree更有意见，因为它总是进行可编辑安装，并使用构建后端来获取顶级依赖。
• uv
• PDM
• Poetry
• pipenv
• pipdeptree。与pip-df tree类似。在pip-deepfreeze中有树形命令，共享了顶级依赖的相同概念。

开发

要运行测试，请使用tox。您将在htmlcov/index.html中获得测试覆盖率报告。安装tox的一个简单方法是pipx install tox。

本项目使用pre-commit来强制执行代码检查（其中black用于代码格式化，isort用于排序导入，mypy用于类型检查）。

为确保在每次提交时本地运行linters，请安装pre-commit（建议使用pipx install pre-commit），并在pip-deepfreeze仓库的本地副本中运行pre-commit install。

要发布

• 选择下一个版本号，形式为X.Y(.Z)。
• towncrier --version X.Y(.Z).
• 检查并提交更新的CHANGELOG.md。
• 在GitHub上，创建一个新的发布。选择形式为vX.Y(.Z)的标签。点击“生成发布说明”并复制CHANGELOG.md中的内容。

贡献

我们欢迎所有类型的贡献。

请查阅问题跟踪器以了解路线图和已知错误。

在打开拉取请求之前，请先创建一个问题以讨论错误或功能请求。