主页 Poetry logo

pyproject.toml 文件

pyproject.toml 文件 #

pyproject.toml 文件的 tool.poetry 部分由多个部分组成。

package-mode #

Poetry 是否以包模式（默认）运行。可选

有关更多信息，请参阅 基本用法。

package-mode = false

name #

包的名称。在包模式下必填

这应该是一个有效的名称，如 PEP 508 中所定义。

name = "my-package"

version #

包的版本。在包模式下必填

这应该是一个有效的 PEP 440 字符串。

version = "0.1.0"
注意
如果您想对您的项目使用语义版本控制，请参阅 此处。

description #

包的简短描述。在包模式下必填

description = "A short description of the package."

license #

包的许可证。

最常见许可证的推荐表示法是（按字母顺序）

  • Apache-2.0
  • BSD-2-Clause
  • BSD-3-Clause
  • BSD-4-Clause
  • GPL-2.0-only
  • GPL-2.0-or-later
  • GPL-3.0-only
  • GPL-3.0-or-later
  • LGPL-2.1-only
  • LGPL-2.1-or-later
  • LGPL-3.0-only
  • LGPL-3.0-or-later
  • MIT

可选，但强烈建议提供此信息。更多标识符列在 SPDX 开源许可证注册表 中。

license = "MIT"
注意
如果您的项目是专有的并且不使用特定许可证，您可以将此值设置为 Proprietary。

authors #

包的作者。在包模式下必填

这是一个作者列表，应包含至少一位作者。作者必须采用 name <email> 的形式。

authors = [
    "Sébastien Eustace <sebastien@eustace.io>",
]

maintainers #

包的维护者。可选

这是一个维护者列表，应与作者区分开来。维护者可能包含电子邮件，并采用 name <email> 的形式。

maintainers = [
    "John Smith <johnsmith@example.org>",
    "Jane Smith <janesmith@example.org>",
]

readme #

对应于包的 README 文件的路径或路径列表。可选

文件可以是任何格式，但如果您打算发布到 PyPI，请牢记 PyPI 友好 README 的建议。README 路径隐式地相对于 pyproject.toml。

注意

路径是否区分大小写遵循平台默认值，但建议保持大小写。

具体来说，您可以为 macOS 和 Windows 上的 README.md 设置 readme = "rEaDmE.mD"，但 Linux 用户在克隆您的仓库后无法 poetry install。这是因为 macOS 和 Windows 不区分大小写，但保留大小写。

README 文件的内容用于填充您分发的元数据的 Description 字段（类似于 setuptools 中的 long_description）。当指定多个文件时，它们将使用换行符连接起来。

[tool.poetry]
# ...
readme = "README.md"

[tool.poetry]
# ...
readme = ["docs/README1.md", "docs/README2.md"]

homepage #

指向项目网站的 URL。可选

homepage = "https://poetry.pythonlang.cn/"

repository #

指向项目仓库的 URL。可选

repository = "https://github.com/python-poetry/poetry"

documentation #

指向项目文档的 URL。可选

documentation = "https://poetry.pythonlang.cn/docs/"

keywords #

包相关的关键字列表。可选

keywords = ["packaging", "poetry"]

classifiers #

描述项目的 PyPI trove 分类器 列表。可选

[tool.poetry]
# ...
classifiers = [
    "Topic :: Software Development :: Build Tools",
    "Topic :: Software Development :: Libraries :: Python Modules"
]
注意

请注意，Python 分类器仍然会自动为您添加，并由您的 python 要求决定。

license 属性也会自动设置 License 分类器。

packages #

要包含在最终分发中的包和模块列表。

如果您的项目结构与 poetry 支持的标准结构不同，您可以指定要包含在最终分发中的包。

[tool.poetry]
# ...
packages = [
    { include = "my_package" },
    { include = "extra_package/**/*.py" },
]

如果您的包存储在“lib”目录中，您必须指定它

[tool.poetry]
# ...
packages = [
    { include = "my_package", from = "lib" },
]

to 参数旨在指定包安装后将位于其中的相对目标路径。这允许您更好地控制项目结构中包的组织方式。

[tool.poetry]
# ...
packages = [
    { include = "my_package", from = "lib", to = "target_package" },
]

如果您想将包限制为特定构建格式，您可以使用 format 指定它

[tool.poetry]
# ...
packages = [
    { include = "my_package" },
    { include = "my_other_package", format = "sdist" },
]

从现在开始，只有 sdist 构建存档将包含 my_other_package 包。

注意

使用 packages 会禁用包自动检测功能，这意味着您必须显式指定“默认”包。

例如，如果您有一个名为 my_package 的包，并且您还想包含另一个名为 extra_package 的包，您将需要显式指定 my_package

packages = [
    { include = "my_package" },
    { include = "extra_package" },
]
注意

Poetry 足够聪明，可以检测 Python 子包。

因此，您只需要指定根包所在的目录即可。

include 和 exclude #

将包含在最终包中的模式列表。

您可以显式地告诉 Poetry，对于打包目的，应该忽略或包含一组 glob。在 exclude 字段中指定的 glob 标识在构建包时不包含的一组文件。

如果包使用 VCS，则 exclude 字段将使用 VCS 的忽略设置进行填充（例如，对于 git 来说是 .gitignore）。

注意
在 include 中显式声明条目将否定 VCS 的忽略设置。
[tool.poetry]
# ...
include = ["CHANGELOG.md"]

您还可以指定这些模式必须包含的格式，如下所示

[tool.poetry]
# ...
include = [
    { path = "tests", format = "sdist" },
    { path = "for_wheel.txt", format = ["sdist", "wheel"] }
]

如果未指定格式，include 默认仅为 sdist。

相反，exclude 默认同时为 sdist 和 wheel。

exclude = ["my_package/excluded.py"]

依赖项和依赖项组 #

Poetry 默认配置为在 PyPI 上查找依赖项。在这种情况下，只需要名称和版本字符串。

[tool.poetry.dependencies]
requests = "^2.13.0"

如果您想使用 私有仓库，您可以将其添加到您的 pyproject.toml 文件中，如下所示

[[tool.poetry.source]]
name = "private"
url = "http://example.com/simple"

如果您配置了多个仓库，您可以明确告诉 Poetry 在哪里查找特定包

[tool.poetry.dependencies]
requests = { version = "^2.13.0", source = "private" }
注意

请注意，声明您的包兼容的 Python 版本是强制性的

[tool.poetry.dependencies]
python = "^3.7"

您可以将依赖项组织到 组 中，以便以更细粒度的方式管理它们。

[tool.poetry.group.test.dependencies]
pytest = "*"

[tool.poetry.group.docs.dependencies]
mkdocs = "*"

有关如何管理依赖项组的更深入了解，请参见 依赖项组，有关其他键和指定版本范围的更多信息，请参见 依赖项规范。

scripts #

本节描述安装包时将安装的脚本或可执行文件

[tool.poetry.scripts]
my_package_cli = 'my_package.console:run'

这里，我们将安装 my_package_cli 脚本，该脚本将执行 my_package 包中 console 模块的 run 函数。

注意
当添加或更新脚本时，运行 poetry install 以使它们在项目的虚拟环境中可用。

extras #

Poetry 支持 extras 以允许表达

  • 可选依赖项，这些依赖项增强了包，但不是必需的；以及
  • 可选依赖项的集群。
[tool.poetry]
name = "awesome"

[tool.poetry.dependencies]
# These packages are mandatory and form the core of this package’s distribution.
mandatory = "^1.0"

# A list of all of the optional dependencies, some of which are included in the
# below `extras`. They can be opted into by apps.
psycopg2 = { version = "^2.9", optional = true }
mysqlclient = { version = "^1.3", optional = true }

[tool.poetry.extras]
mysql = ["mysqlclient"]
pgsql = ["psycopg2"]
databases = ["mysqlclient", "psycopg2"]

使用 Poetry 安装包时，您可以使用 -E|--extras 选项指定 extras

poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql

您未指定的任何 extras 将被删除。请注意，此行为不同于 可选依赖项组 未被选中用于安装，例如，那些未通过 install --with 指定的。

您可以使用 --all-extras 选项安装所有 extras

poetry install --all-extras
注意

请注意，install --extras 和上面提到的变体（--all-extras、--extras foo 等）仅适用于当前项目中定义的依赖项。如果您想安装依赖项定义的 extras，您必须在依赖项本身中表达这一点

[tool.poetry.dependencies]
pandas = {version="^2.2.1", extras=["computation", "performance"]}

[tool.poetry.group.dev.dependencies]
fastapi = {version="^0.92.0", extras=["all"]}

安装或指定 Poetry 构建的包时，本节中定义的 extras 可以按照 PEP 508 中的描述进行激活。

例如，使用 pip 安装包时，databases extra 所需的依赖项可以按如下所示安装。

pip install awesome[databases]
注意

为每个 extra 指定的依赖项必须已定义为项目依赖项。

列在 依赖项组 中的依赖项不能指定为 extras。

plugins #

Poetry 支持任意插件，这些插件作为生态系统标准的 入口点 公开，并且可以使用 importlib.metadata 发现。这类似于（并且与）setuptools 的入口点功能兼容。注册插件的语法为

[tool.poetry.plugins] # Optional super table

[tool.poetry.plugins."A"]
B = "C:D"

它们是

  • A - 插件类型，例如 poetry.plugin 或 flake8.extension
  • B - 插件名称
  • C - Python 模块导入路径
  • D - 插件的入口点（函数或类）

示例（来自 poetry-plugin-export）

[tool.poetry.plugins."poetry.application.plugin"]
export = "poetry_plugin_export.plugins:ExportApplicationPlugin"

urls #

除了基本 URL（homepage、repository 和 documentation）之外，您还可以指定 urls 部分中的任何自定义 URL。

[tool.poetry.urls]
"Bug Tracker" = "https://github.com/python-poetry/poetry/issues"

如果您在 PyPI 上发布您的包，它们将出现在 Project Links 部分。

Poetry 和 PEP-517 #

PEP-517 引入了一种标准方法来定义用于构建 Python 项目的替代构建系统。

Poetry 符合 PEP-517，通过提供一个轻量级的核心库，因此，如果您使用 Poetry 来管理您的 Python 项目，您应该在 pyproject.toml 文件的 build-system 部分中引用它，如下所示

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
注意
使用 new 或 init 命令时，此部分将自动添加。
注意
如果您的 pyproject.toml 文件仍然直接引用 poetry 作为构建后端，您应该将其更新为改为引用 poetry-core。