孵化最小要求

Hatchling插件，用于创建指定最小版本的可选依赖项

理由

当创建一个库时，指定所需依赖项的最小版本通常很有用。然而，pip的默认行为是安装满足您要求的包的最新版本。因此，如果您没有仔细测试您所需的最小依赖项，您可能无意中引入了与您指定的最小版本不兼容的更改。

此插件将检查您的包依赖项，并动态地将额外的（默认命名为min-reqs）添加到您的pyproject.toml文件的project.optional-dependencies表中。此额外项将包含所有依赖项，并固定到其最小版本。

这使得您可以在CI上轻松测试您的包与声明的最小依赖项，或者安装用于本地开发的最低依赖项。

用法

在您的pyproject.toml中进行以下更改

• 将hatch-min-requirements添加到[build-system.requires]中。
• 添加一个[tool.hatch.metadata.hooks.min_requirements]表。

[build-system]
requires = ["hatchling", "hatch-min-requirements"]
build-backend = "hatchling.build"

[tool.hatch.metadata.hooks.min_requirements]

然后，您可以使用min-reqs额外项安装您的包，并且它将动态使用依赖项的最小兼容版本。

pip install -e .[min-reqs]

环境变量

可以使用环境变量来配置行为。以下详细说明

实用工具

此软件包提供了两个可以直接使用（无需作为 hatch 插件）的便利函数。

• hatch_min_requirements.sub_min_compatible_version

  接受一个 pip 需求字符串，并返回一个新的需求字符串，其中已用最低兼容版本替换。

  >>> sub_min_compatible_version("numpy")
  'numpy==1.3.0'
  >>> sub_min_compatible_version("numpy>=1.4.1")
  'numpy==1.4.1'
  >>> sub_min_compatible_version("numpy>1.3")
  'numpy==1.4.1'
  >>> sub_min_compatible_version("numpy[extra1,extra2]>=1.20,<2.0")
  'numpy[extra1,extra2]==1.20.0'
  >>> sub_min_compatible_version("numpy[extra]<2; python_version == '3.6'")
  "numpy[extra]==1.3.0 ; python_version == '3.6'"
  

• hatch_min_requirements.patch_pyproject

  接受一个指向 pyproject.toml 文件的路径，并将其修补以包含 min-reqs 额外功能。原始文件使用 .BAK 扩展名备份。

  >>> patch_pyproject("path/to/pyproject.toml")
  

注意事项

无约束的依赖项

在没有约束的情况下声明依赖项（例如：foo）的情况下，插件 将 在 PyPI 上搜索包的最低可用版本。这里的目的是鼓励 精确 的需求绑定。如果您想禁用此行为并保持无约束指定符不变，您可以将 MIN_REQS_PIN_UNCONSTRAINED 环境变量设置为 0 或 False，或使用离线模式，设置 MIN_REQS_OFFLINE=1（见下文）。

离线模式

在类似于上限（《<X.Y》），非包含下限（《>X.Y》）和排除（《!=X.Y》）的情况下，不可能在不从 PyPI 获取可用版本的情况下声明最低版本。默认情况下，此插件 将 尝试连接到 PyPI 以确定兼容的最低版本字符串。如果您想禁用此行为，可以将 MIN_REQS_OFFLINE 环境变量设置为 1 或 True。

MIN_REQS_OFFLINE=1 pip install -e .[min-reqs]

在离线模式下，在非包含下限之后，插件将不会尝试猜测包的下一个兼容版本。相反，插件将简单地使用您声明的依赖项（这意味着您不会测试下限）。如果您想在不连接到 PyPI 的情况下测试下限，您应使用 包含 的下限来绑定依赖项

[project]
dependencies = [
    "foo>=1.2.3"  # will be pinned to "foo==1.2.3"
    "baz~=1.2"    # will be pinned to "baz==1.2"
    "bar>1.2.3"   # will be unchanged
]

pip 与标准库工具的使用

获取包的可用版本不是一件简单的事情，而 pip 是执行此操作的 事实 工具。如果构建环境中提供了 pip，则此插件将使用它来获取包的可用版本。但是，您必须通过在 pyproject.toml 中的 build-system.requires 中添加 pip 来选择此行为。

[build-system]
requires = ["hatchling", "hatch-min-requirements", "pip"]

要明确选择不使用 pip（即使它可用）并仅使用标准库工具，您可以将 MIN_REQS_TRY_PIP 环境变量设置为 0 或 False。

待办事项

• 将 offline 和 no-pip 选项添加到 pyproject 中的 min_requirements 表