Martin Thoma A blog about Code, the Web and Cyberculture

pyproject.toml

· by

Contents

The pyproject.toml file allows package creators to define the build system as a dependency as well as a project's metadata. Also, other kinds of metadata and the install requirements can be defined in it.

If you are interested in a sample project, try pypa/sampleproject or try the packaging tutorial.

Example

[project]
name = "infer_pyproject"
version = "0.1.0"
description = "Create a pyproject.toml file for an existing project."
authors = [
    {name = "Martin Thoma", email="[email protected]"},
    {email = "[email protected]"}
]
license = {file = "LICENSE.txt"}
readme = "README.md"
requires-python = ">=3.6"

keywords = ["packaging", "dependency", "infer", "pyproject.toml"]

classifiers = [
    "Topic :: Software Development"
]

# Requirements: This is done differently by poetry!
dependencies = [
    "Click>=7.0"
]

[project.optional-dependencies]
dev = [
    "black>=18.3-alpha.0",
]

[project.urls]
homepage = "https://github.com/MartinThoma/infer_pyproject"
documentation = "https://github.com/MartinThoma/infer_pyproject"
repository = "https://github.com/MartinThoma/infer_pyproject"

[project.scripts]
poetry = "infer_pyproject.cli:main"

[build-system]
requires = [
    "setuptools >= 35.0.2",
    "setuptools_scm >= 2.0.0, <3"
]
build-backend = "setuptools.build_meta"

[tool.black]
line-length = 88
target_version = ['py36']
include = '\.pyi?$'
exclude = '''

(
  /(
      \.eggs         # exclude a few common directories in the
    | \.git          # root of the project
    | \.hg
    | \.mypy_cache
    | \.tox
    | \.venv
    | _build
    | buck-out
    | build
    | dist
  )/
  | foo.py           # also separately exclude a file named foo.py in
                     # the root of the project
)
'''

History

Tools

Python Package
A bundle of software. This includes code and meta-data, such as requirements, a short and a long description, the license. It also contains instructions on how to build the software. Formerly this was done with distutils.
distutils
Lets you create source distributions (python setup.py sdist). Sometimes building takes a long time, so you might want to share already built distributions. You can do that with python setup.py bdist.
setuptools
Like distutils, but a 3rd party library. It is the de facto standard, but does not come with Python.
setup.py dependency declaration
Python file which specifies a package. As it can be arbitrary code, there is no way to know the dependencies of a package for sure without executing setup.py.
PyPI (Python Package Index) software repository
PyPI is the official third-party software repository for Python. Here people can share their code in the form of Python packages.
easy_install
Easy_install is a package manager which is replaced by pip, because it could not uninstall and did not know what was installed. Other reasons as well.
egg distribution distribution format
"Egg" is a single-file importable distribution format for Python-related projects. Eggs are to Pythons as Jars are to Java, but eggs are richer than jars; they hold interesting metadata such as licensing details, release dependencies, ... (source). It is a zip file.
pip
pip is a de facto standard package manager for Python. It allows you to install packages and installs required packages. pip introduced requirements.txt.
requirements.txt dependency declaration
It allows pinning versions of a dependency. The setup.py includes abstract requirements, the requirements.txt includes concrete ones. Abstract requirements are more flexible, concrete ones are stable.
wheel distribution distribution format
The wheel binary package format is specified in PEP 427. It is similar to egg distributions. It is a zip file.
twine
Allows you to securely upload a package to PyPI.
conda
conda is a Python-agnostic packaging tool and installer. If you need more than Python / if you don't have Python installed. It supports C, Fortran, R, Perl, Java, ...
pipfile and pipfile.lock dependency declaration
A pipfile should be easier to maintain than multiple requirements.txt files, e.g. for testing / environments (dev, stage, prod). The pipfile.lock is automatically generated and tracks interdependencies of the required packages; it is similar to gemfile.lock in Ruby and yarn.lock in JavaScript. pipenv is the tool to use with those files. SO-Questions: 28 for pipfile, 485 for pipenv
pyproject.toml dependency declaration
A build-system independent way to specify project dependencies. setup.py is bad as it is 3rd party and requires code execution. It is a way to step away from distutils / setuptools. The specified build system can be setuptools as well. The pyproject.toml is similar to the Cargo.toml of Rust
pyenv
Install different Python versions. It is similar to rbenv from Ruby.
pipenv
Wrapper for virtualenv. Has 485 questions on SO. See pipfile for more info.
virtualenvwrapper
Another virtualenv wrapper. Has 570 questions on SO.
Poetry
Meant to be a successor of pipenv, but seems not production-ready yet (source, 13 SO questions).
DepHell
A Python project management tool. Can convert between setup.py <-> pyproject.toml.
flit
Flit is a way to put Python packages and modules on PyPI. It is a 3rd party replacement for setuptools, but has no SO tag.

See also