What is pyproject.toml file for?

Yes, pyproject.toml is the specified file format of PEP 518 which contains the build system requirements of Python projects.

This solves the build-tool dependency chicken and egg problem, i.e. pip can read pyproject.toml and what version of setuptools or wheel one may need.

If you need a setup.py for an editable install, you could use a shim in setup.py:

#!/usr/bin/env pythonimport setuptoolsif __name__ == "__main__":    setuptools.setup()

pyproject.toml is the new unified Python project settings file that replaces setup.py.Editable installs still need a setup.py: import setuptools; setuptools.setup()

To use pyproject.toml, run python -m pip install .

Then, if the project is using poetry instead of pip, you can install dependencies (into %USERPROFILE%\AppData\Local\pypoetry\Cache\virtualenvs) like this:

poetry install

And then run dependencies like pytest:

poetry run pytest tests/

And pre-commit (uses .pre-commit-config.yaml):

poetry run pre-commit installpoetry run pre-commit run --all-files

Currently there are multiple packaging tools being popular in Python community and while setuptools still seems to be prevalent it's not a de facto standard anymore. This situation creates a number of hassles for both end users and developers:

1. For setuptools-based packages installation from source / build of a distribution can fail if one doesn't have setuptools installed;
2. Packages based on other packaging tools can not be installed from source using pip. One has to install the packaging tool first and then use tool-specific commands to install/​build a distribution package;
3. If package author decides to change the packaging tool, workflows must be changed as well to use different tool-specific commands.

pyproject.toml is a new configuration file introduced by PEP 517 and PEP 518 to solve these problems:

... think of the (rough) steps required to produce a built artifact for a project:

1. The source checkout of the project.
2. Installation of the build system.
3. Execute the build system.

This PEP [518] covers step #2. PEP 517 covers step #3 ...

Any tool can also extend this file with its own section (table) to accept tool-specific options, but it's up to them and not required.

For setuptools-based packages pyproject.toml is not strictly meant to replace setup.py, but rather to ensure its correct execution if it's still needed. For other packaging tools – yes, it is:

Where the build-backend key exists, this takes precedence and the source tree follows the format and conventions of the specified backend (as such no setup.py is needed unless the backend requires it). Projects may still wish to include a setup.py for compatibility with tools that do not use this spec.

"Editable install" is a setuptools-specific feature and as such it is not supported by PEP 517:

Install Options:  -e, --editable <path/url>   Install a project in editable mode (i.e. setuptools "develop mode")

To install setuptools-based package in an editable mode it needs to have a setup.py file with at least minimal content:

from setuptools import setupsetup()