pyproject.toml 配置文件

这个文件存在于模块或包的旁边。

备注

旧版本的 Flit（到 0.11 为止）使用一个 flit.ini 文件来提供类似的信息。这些文件不再适用于 Flit 3 及以上版本。

运行 python3 -m flit.tomlify，将 flit.ini 文件转换为 pyproject.toml。

建设系统部分

这告诉像 pip 这样的工具要用 flit 来构建你的项目。这是由 PEP 517 定义的一个标准。对于任何使用 Flit 的新项目，它看起来像这样：

[build-system]
requires = ["flit_core >=3.2,<4"]
build-backend = "flit_core.buildapi"

版本约束：

目前，所有的软件包都应该指定 <4，这样它们就不会受到下一个主要版本变化的影响。
新风格的元数据 requires flit_core >=3.2
Old style metadata requires flit_core >=2,<4
The older flit.ini file requires flit_core <3.
TOML 在 1.0 版本中的新功能需要 flit_core >=3.4。
flit_core 3.3 是支持 Python 3.4 和 3.5 的最后一个版本。支持这些 Python 版本的软件包只能使用 TOML v0.5。
Only flit_core 2.x can build packages on Python 2, so packages still supporting Python 2 cannot use new-style metadata (the [project] table).

新风格的元数据

3.2 新版功能.

指定项目元数据的新标准方式是在 [project] 表中，如 PEP 621 所定义。Flit 现在可以使用这个表或旧的 [tool.flit.metadata] 表（下面描述的），但它不允许你把它们混合起来。

一个简单的 [project] 表可能看起来像这样：

[project]
name = "astcheck"
authors = [
    {name = "Thomas Kluyver", email = "thomas@kluyver.me.uk"},
]
readme = "README.rst"
classifiers = [
    "License :: OSI Approved :: MIT License",
]
requires-python = ">=3.5"
dynamic = ["version", "description"]

允许的字段是：

name: 你的软件包在 PyPI 上的名称。这个字段是必须的。对于 Flit 来说，这也是默认指向你的软件包的导入名称（如果需要不同的话，请看模块部分）。
version: 版本号是一个字符串。如果你想让 Flit 从 __version__ 属性中得到这个数字，请不要在 TOML 配置中使用它，并在 dynamic 字段中包含 “version”。
description: 你的项目的单行描述。如果你想让 Flit 从模块的文档串中得到这个描述，请不要在 TOML 配置中加入这个描述，并在 dynamic 字段中加入 “description”。
readme: 一个文件的路径（相对于 .toml 文件），该文件包含对你的软件包的较长描述，以便在 PyPI 上显示。这应该用 reStructuredText、Markdown 或纯文本编写，文件名应该有适当的扩展名（.rst、.md 或 .txt）。另外，readme 可以是一个表，有 file 键（相对路径）或 text 键（字面文本），还有一个可选的 content-type 键（例如 text/x-rst）。
requires-python: 一个版本的指定符，表示这需要的 Python 版本，例如 ~=3.3 或 >=3.3,<4，它们是等效的。
license: 一个带有 file 键（许可证文件的相对路径）或 text 键（许可证文本）的表。
authors: 带有 name 和 email 键（都是可选的）的表格列表，描述项目的作者。
maintainers: 格式与 authors 相同。
keywords: 一个帮助搜索你的包的单词列表。
classifiers: Trove classifiers 清单。在列表中加入 Private :: Do Not Upload，以防止私人软件包被意外地上传到 PyPI。
dependencies & optional-dependencies: 参见 Dependencies。
urls: 参见：URL 表。
scripts & gui-scripts: 参见：脚本部分。
entry-points: 参见：切入点部分。
dynamic: 一个没有在这里指定的字段名的列表，Flit 应该在构建时为其找到一个值。只有 “version” 和 “description” 被接受。

Dependencies

dependencies 字段是这个包需要的 PyPI 的其他包的列表。每个包后面都可以有一个版本说明，如 >=4.1，和/或分号后的 environment marker。例如：

dependencies = [
    "requests >=2.6",
    "configparser; python_version == '2.7'",
]

[project.optional-dependencies] 表包含了每个可选功能所需的软件包列表。要求的指定格式与 dependencies 相同。比如说：

[project.optional-dependencies]
test = [
    "pytest >=2.7.3",
    "pytest-cov",
]
doc = ["sphinx"]

你可以把这些可选功能称为任何你想要的东西，尽管 test 和 doc 是常见的功能。你可以在软件包名称或目录后面的方括号中指定它们的安装，例如：pip install '.[test]'。

URL 表

你在 pypi.org 的项目页面可以显示一些链接。例如，你可以把人们指向文档或错误跟踪器。

这一部分在文件中被称为 [project.urls]。你可以在里面使用任何名字。这里是用于 flit 的：

[project.urls]
Documentation = "https://flit.readthedocs.io/en/latest/"
Source = "https://github.com/pypa/flit"

脚本部分

这一部分在文件中被称为 [project.scripts]。每个键和值都描述了一个要和你的软件包一起安装的 shell 命令。这些工作就像 setuptools 的 ‘入口点’。下面是 flit 的部分：

[project.scripts]
flit = "flit:main"

这将创建一个 flit 命令，它将调用从 flit 导入的函数 main()。

一个名为 [project.gui-scripts] 的类似表格定义了启动 GUI 的命令。这只在 Windows 上有区别，因为 GUI 脚本的运行没有控制台。

切入点部分

你可以使用名为 [project.entry-points.groupname] 的部分来声明 entry points。例如，从你的软件包中提供一个 pygments lexer：

[project.entry-points."pygments.lexers"]
dogelang = "dogelang.lexer:DogeLexer"

在每个 package:name 值中，冒号前的部分应该是一个可导入的模块名称，后半部分应该是该模块中可访问的对象名称。暴露什么对象的细节取决于你要扩展的应用程序。

如果组名包含一个点，必须加引号（"pygments.lexers" 上面）。脚本入口是在 scripts tables 中定义的，所以你不能在这里使用组名 console_scripts 或 gui_scripts。

模块部分

如果你的软件包将有不同的安装和导入名称，你应该在 [project] 表中指定安装（PyPI）名称（见上文），并在 [tool.flit.module] 表中指定导入名称：

[project]
name = "pynsist"
# ...

[tool.flit.module]
name = "nsist"

Old style metadata

Flit’s older way to specify metadata is in a [tool.flit.metadata] table, along with [tool.flit.scripts] and [tool.flit.entrypoints], described below. This is still recognised for now, but you can’t mix it with 新风格的元数据.

There are three required fields:

module: The name of the module/package, as you’d use in an import statement.
author: Your name
author-email: Your email address

e.g. for flit itself

[tool.flit.metadata]
module = "flit"
author = "Thomas Kluyver"
author-email = "thomas@kluyver.me.uk"

在 1.1 版更改: home-page was previously required.

The remaining fields are optional:

home-page

A URL for the project, such as its Github repository.

requires

A list of other packages from PyPI that this package needs. Each package may be followed by a version specifier like (>=4.1) or >=4.1, and/or an environment marker after a semicolon. For example:

requires = [
    "requests >=2.6",
    "configparser; python_version == '2.7'",
]

requires-extra

Lists of packages needed for every optional feature. The requirements are specified in the same format as for requires. The requirements of the two reserved extras test and doc as well as the extra dev are installed by flit install. For example:

[tool.flit.metadata.requires-extra]
test = [
    "pytest >=2.7.3",
    "pytest-cov",
]
doc = ["sphinx"]

1.1 新版功能.

description-file

A path (relative to the .toml file) to a file containing a longer description of your package to show on PyPI. This should be written in reStructuredText, Markdown or plain text, and the filename should have the appropriate extension (.rst, .md or .txt).

classifiers

A list of Trove classifiers. Add Private :: Do Not Upload into the list to prevent a private package from uploading on PyPI by accident.

requires-python

A version specifier for the versions of Python this requires, e.g. ~=3.3 or >=3.3,<4 which are equivalents.

dist-name

If you want your package’s name on PyPI to be different from the importable module name, set this to the PyPI name.

keywords

Comma separated list of words to help with searching for your package.

license

The name of a license, if you’re using one for which there isn’t a Trove classifier. It’s recommended to use Trove classifiers instead of this in most cases.

maintainer, maintainer-email

Like author, for if you’ve taken over a project from someone else.

Here was the metadata section from flit using the older style:

[tool.flit.metadata]
module="flit"
author="Thomas Kluyver"
author-email="thomas@kluyver.me.uk"
home-page="https://github.com/pypa/flit"
requires=[
    "flit_core >=2.2.0",
    "requests",
    "docutils",
    "tomli",
    "tomli-w",
]
requires-python=">=3.6"
description-file="README.rst"
classifiers=[
    "Intended Audience :: Developers",
    "License :: OSI Approved :: BSD License",
    "Programming Language :: Python :: 3",
    "Topic :: Software Development :: Libraries :: Python Modules",
]

URLs subsection

Your project’s page on pypi.org can show a number of links, in addition to the home-page URL described above. You can point people to documentation or a bug tracker, for example.

This section is called [tool.flit.metadata.urls] in the file. You can use any names inside it. Here it is for flit:

[tool.flit.metadata.urls]
Documentation = "https://flit.readthedocs.io/en/latest/"

1.0 新版功能.

脚本部分

A [tool.flit.scripts] table can be used along with [tool.flit.metadata]. It is in the same format as the newer [project.scripts] table described above.

切入点部分

[tool.flit.entrypoints] tables can be used along with [tool.flit.metadata]. They are in the same format as the newer [project.entry-points] tables described above.

Sdist 部分

2.0 新版功能.

当你使用 flit build 或 flit publish 时，Flit 会建立一个 sdist（源码分布）tarball，其中包含被检查到版本控制（git 或 mercurial）的文件。如果你想要更多的控制，或者它不能识别你的版本控制系统，你可以在这部分给出路径列表或 glob 模式作为 include 和 exclude。例如：

[tool.flit.sdist]
include = ["doc/"]
exclude = ["doc/*.html"]

这些路径：

始终使用 / 作为分隔符（POSIX 风格）
必须是包含 pyproject.toml 的目录的相对路径。
不能进入该目录之外（没有 ../ 的路径）。
不能包含控制字符或 <>:"\\
不能使用递归 glob 模式（**/）
可以指代目录，在这种情况下，它们包括该目录下的一切，包括子目录
应该与它们所指的文件的大小写相匹配，因为不区分大小写的匹配是依赖于平台的

不适用的情况比适用的情况优先。

备注

如果你没有使用 flit build，而是通过其他构建前端使用 flit_core，Flit 不会检查 VCS 中的文件，而是构建一个 ‘最小’ 的 sdist（其中包括构建轮子所需的文件）。你必须调整你的包含/排除规则，以达到与你用 flit build 得到的相同结果。

External data section

3.7 新版功能.

Data files which your code will use should go inside the Python package folder. Flit will package these with no special configuration.

However, sometimes it’s useful to package external files for system integration, such as man pages or files defining a Jupyter extension. To do this, arrange the files within a directory such as data, next to your pyproject.toml file, and add a section like this:

[tool.flit.external-data]
directory = "data"

Paths within this directory are typically installed to corresponding paths under a prefix (such as a virtualenv directory). E.g. you might save a man page for a script as (data)/share/man/man1/foo.1.

Whether these files are detected by the systems they’re meant to integrate with depends on how your package is installed and how those systems are configured. For instance, installing in a virtualenv usually doesn’t affect anything outside that environment. Don’t rely on these files being picked up unless you have close control of how the package will be installed.

If you install a package with flit install --symlink, a symlink is made for each file in the external data directory. Otherwise (including development installs with pip install -e), these files are copied to their destination, so changes here won’t take effect until you reinstall the package.

备注

For users coming from setuptools: external data corresponds to setuptools’ data_files parameter, although setuptools offers more flexibility.