File Format

The build system dependencies will be stored in a file named pyproject.toml that is written in the TOML format [6].

This format was chosen as it is human-usable (unlike JSON [7]), it is flexible enough (unlike configparser [9]), stems from a standard (also unlike configparser [9]), and it is not overly complex (unlike YAML [8]). The TOML format is already in use by the Rust community as part of their Cargo package manager [14] and in private email stated they have been quite happy with their choice of TOML. A more thorough discussion as to why various alternatives were not chosen can be read in the Other file formats section. The authors do realize, though, that choice of configuration file format is ultimately subjective and a choice had to be made and the authors prefer TOML for this situation.

Below we list the tables that tools are expected to recognize/respect. Tables not specified in this PEP are reserved for future use by other PEPs.

build-system table

The [build-system] table is used to store build-related data. Initially only one key of the table will be valid and is mandatory for the table: requires. This key must have a value of a list of strings representing PEP 508 dependencies required to execute the build system (currently that means what dependencies are required to execute a setup.py file).

For the vast majority of Python projects that rely upon setuptools, the pyproject.toml file will be:

[build-system]
# Minimum requirements for the build system to execute.
requires = ["setuptools", "wheel"]  # PEP 508 specifications.

Because the use of setuptools and wheel are so expansive in the community at the moment, build tools are expected to use the example configuration file above as their default semantics when a pyproject.toml file is not present.

Tools should not require the existence of the [build-system] table. A pyproject.toml file may be used to store configuration details other than build-related data and thus lack a [build-system] table legitimately. If the file exists but is lacking the [build-system] table then the default values as specified above should be used. If the table is specified but is missing required fields then the tool should consider it an error.

tool table

The [tool] table is where any tool related to your Python project, not just build tools, can have users specify configuration data as long as they use a sub-table within [tool], e.g. the flit tool would store its configuration in [tool.flit].

We need some mechanism to allocate names within the tool.* namespace, to make sure that different projects don’t attempt to use the same sub-table and collide. Our rule is that a project can use the subtable tool.$NAME if, and only if, they own the entry for $NAME in the Cheeseshop/PyPI.

JSON Schema

To provide a type-specific representation of the resulting data from the TOML file for illustrative purposes only, the following JSON Schema [15] would match the data format:

{
    "$schema": "http://json-schema.org/schema#",

    "type": "object",
    "additionalProperties": false,

    "properties": {
        "build-system": {
            "type": "object",
            "additionalProperties": false,

            "properties": {
                "requires": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": ["requires"]
        },

        "tool": {
            "type": "object"
        }
    }
}

A semantic version key

For future-proofing the structure of the configuration file, a semantics-version key was initially proposed. Defaulting to 1, the idea was that if any semantics changes to previously defined keys or tables occurred which were not backwards-compatible, then the semantics-version would be incremented to a new number.

In the end, though, it was decided that this was a premature optimization. The expectation is that changes to what is pre-defined semantically in the configuration file will be rather conservative. And in the instances where a backwards-incompatible change would have occurred, different names can be used for the new semantics to avoid breaking older tools.

A more nested namespace

An earlier draft of this PEP had a top-level [package] table. The idea was to impose some scoping for a semantics versioning scheme (see A semantic version key for why that idea was rejected). With the need for scoping removed, the point of having a top-level table became superfluous.

Other table names

Another name proposed for the [build-system] table was [build]. The alternative name is shorter, but doesn’t convey as much of the intention of what information is store in the table. After a vote on the distutils-sig mailing list, the current name won out.

Other file formats

Several other file formats were put forward for consideration, all rejected for various reasons. Key requirements were that the format be editable by human beings and have an implementation that can be vendored easily by projects. This outright excluded certain formats like XML which are not friendly towards human beings and were never seriously discussed.

{
    "build": {
        "requires": [
            "setuptools",
            "wheel>=0.27"
        ]
    }
}

build:
    requires:
        - setuptools
        - wheel>=0.27

[build]
requires =
    setuptools
    wheel>=0.27

# The build configuration
{"build": {"requires": ["setuptools",
                        "wheel>=0.27", # note the trailing comma
                        # "numpy>=1.10" # a commented out data line
                        ]
# and here is an arbitrary comment.
           }
 }

Sticking with setup.cfg

There are two issues with setup.cfg used by setuptools as a general format. One is that they are .ini files which have issues as mentioned in the configparser discussion above. The other is that the schema for that file has never been rigorously defined and thus it’s unknown which format would be safe to use going forward without potentially confusing setuptools installations.

Other file names

Several other file names were considered and rejected (although this is very much a bikeshedding topic, and so the decision comes down to mostly taste).

pysettings.toml

Most reasonable alternative.

pypa.toml

While it makes sense to reference the PyPA [11], it is a somewhat niche term. It’s better to have the file name make sense without having domain-specific knowledge.

pybuild.toml

From the restrictive perspective of this PEP this filename makes sense, but if any non-build metadata ever gets added to the file then the name ceases to make sense.

pip.toml

Too tool-specific.

meta.toml

Too generic; project may want to have its own metadata file.

setup.toml

While keeping with traditional thanks to setup.py, it does not necessarily match what the file may contain in the future (e.g. is knowing the name of a project inherently part of its setup?).

pymeta.toml

Not obvious to newcomers to programming and/or Python.

pypackage.toml & pypackaging.toml

Name conflation of what a “package” is (project versus namespace).

pydevelop.toml

The file may contain details not specific to development.

pysource.toml

Not directly related to source code.

pytools.toml

Misleading as the file is (currently) aimed at project management.

dstufft.toml

Too person-specific. ;)