文件pyproject.toml¶

spec¶

pyproject.toml 文件是用 TOML 编写的。当前指定了三个表，即 [build-system]、[project] 和 [tool]。
注意：只有 [build-system] 表的 requires 字段是必需的

当 pyproject.toml 文件不存在时，构建工具应使用下面的示例配置文件作为其默认语义:

[build-system]
# Minimum requirements for the build system to execute.
requires = ["setuptools"]

示例:

[project]
name = "mypackage"
version = "0.0.1"
dependencies = [
    "requests",
    'importlib-metadata; python_version<"3.8"',
]

[build-system] section¶

declare which build backend you use and which other dependencies are needed to build your project.

setuptools示例:

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"


[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

hatchling示例:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Flit 示例:

[build-system]
requires = ["flit_core>=3.4"]
build-backend = "flit_core.buildapi"

PDM 示例:

[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"

[project] section¶

specify your project’s basic metadata, such as the dependencies, your name, etc.

备注

As of August 2024, Poetry is a notable build backend that does not use the [project] table, it uses the [tool.poetry] table instead. Also, the setuptools build backend supports both the [project] table, and the older format in setup.cfg or setup.py.

[project]
dependencies = [
  "httpx",
  "gidgethub[httpx]>4.0.0",
  "django>2.1; os_name != 'nt'",
  "django>2.0; os_name == 'nt'",
]

示例:

[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
  { name="Example Author", email="author@example.com" },
]
maintainers = [
  {name = "Brett Cannon", email = "brett@example.com"}
]
description = "A small example package"

readme = "README.md"
# readme = {file = "README.txt", content-type = "text/markdown"}
# readme = {file = "README.rst", content-type = "text/x-rst"}

license = {file = "LICENSE"}
keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
requires-python = ">=3.8"

# A list of PyPI classifiers that apply to your project.
classifiers = [
    # How mature is this project? Common values are
    #   3 - Alpha
    #   4 - Beta
    #   5 - Production/Stable
    "Development Status :: 4 - Beta",

    # Indicate who your project is intended for
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Build Tools",

    # Specify the Python versions you support here.
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",

    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",

    # PyPI will always reject packages with classifiers beginning with Private ::
    Private :: Do Not Upload classifier,
]

dynamic metadata¶

When a field is dynamic, it is the build backend’s responsibility to fill it. Consult your build backend’s documentation to learn how it does it

setuptools示例:

[project]
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "package.__version__"}

[project.urls] sub section¶

允许您列出任意数量的额外链接以在 PyPI 上显示。通常，这可能是源、文档、问题跟踪器等:

[project.urls]
Homepage = "https://github.com/pypa/sampleproject"
Issues = "https://github.com/pypa/sampleproject/issues"
# 如果key带空格需要加引号
"Official Website" = "https://example.com"

[project.optional-dependencies] sub section¶

[project.optional-dependencies]
gui = ["PyQt5"]
cli = [
  "rich",
  "click",
]

指定了gui参数，则会安装 PyQt5 依赖库:

pip install your-project-name[gui]

[project.scripts] sub section¶

To install a command as part of your package, declare it in the [project.scripts] table:

[project.scripts]
spam-cli = "spam:main_cli"

# after installing your project, a spam-cli command will be available.
# Executing this command will do the equivalent of `from spam import main_cli; main_cli()`

[project.gui-scripts] sub section¶

windows 专用:

[project.gui-scripts]
spam-gui = "spam:main_gui"

Advanced plugins¶

Some packages can be extended through plugins.
Examples include Pytest and Pygments.
To create such a plugin, you need to declare it in a subtable of [project.entry-points] like this:

[project.entry-points.”spam.magical”] tomatoes = “spam:main_tomatoes”

pipx 示例

[project.entry-points."pipx.run"]
greetings = "greetings.cli:app"

[tool] section¶

tool-specific subtables, e.g., [tool.hatch], [tool.black], [tool.mypy].