The pyproject.toml config file¶
This file lives next to the module or package.
Older version of Flit (up to 0.11) used a flit.ini file for
similar information. Flit can still read these files for now, but you should
python3 -m flit.tomlify to convert a
flit.ini file to
Build system section¶
This tells tools like pip to build your project with flit. It’s a standard defined by PEP 517. For any project using Flit, it will look like this:
[build-system] requires = ["flit"] build-backend = "flit.buildapi"
This section is called
[tool.flit.metadata] in the file.
There are four required fields:
- The name of the module/package, as you’d use in an import statement.
- Your name
- Your email address
- A URL for the project, such as its Github repository.
e.g. for flit itself
[tool.flit.metadata] module = "flit" author = "Thomas Kluyver" author-email = "firstname.lastname@example.org" home-page = "https://github.com/takluyver/flit"
The remaining fields are optional:
A list of other packages from PyPI that this package needs. Each package may be followed by a version specifier in parentheses, like
(>=4.1), and/or an environment marker after a semicolon. For example:
requires = ["requests (>=2.6)", "configparser; python_version == '2.7'" ]
Packages that are required for development. This field is in the same format as
These are not (yet) encoded in the wheel, but are used when doing
- A path (relative to the .ini file) to a file containing a longer description of your package to show on PyPI. This should be written in reStructuredText, if your long description is not valid reStructuredText, a warning will be printed, and it will be interpreted as plain text on PyPI.
- A list of Trove classifiers.
- A version specifier for the versions of Python this requires, e.g.
>=3.3,<4which are equivalents.
- If you want your package’s name on PyPI to be different from the importable module name, set this to the PyPI name.
- Space separated list of words to help with searching for your package.
- 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’s the full metadata section from flit itself:
[tool.flit.metadata] module="flit" author="Thomas Kluyver" author-email="email@example.com" home-page="https://github.com/takluyver/flit" requires=["requests", "docutils", "requests_download", "pytoml", ] requires-python="3" description-file="README.rst" classifiers=["Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Programming Language :: Python :: 3", "Topic :: Software Development :: Libraries :: Python Modules", ]
This section is called
[tool.flit.scripts] in the file.
Each key and value describes a shell command to be installed along with
your package. These work like setuptools ‘entry points’. Here’s the section
[tool.flit.scripts] flit = "flit:main"
This will create a
flit command, which will call the function
Entry points sections¶
You can declare entry points
using sections named
[tool.flit.entrypoints.groupname]. E.g. to
provide a pygments lexer from your package:
[tool.flit.entrypoints."pygments.lexers"] dogelang = "dogelang.lexer:DogeLexer"
package:name value, the part before the colon should be an
importable module name, and the latter part should be the name of an object
accessible within that module. The details of what object to expose depend on
the application you’re extending.