PyProject
The future of Python builds, distribution, and packaging lies in pyproject.toml. The protocol has been incrementally built through PEPs 517, 518, PEP 621, PEP 631, and PEP 660.
Build System
This is the focus of PEP 517. A minimal example of the Build System section is:
[build-system] requires = ["setuptools"] build-backend = "setuptools.build_meta"
From here, different backends will have different requirements.
Setuptools
To use the setuptools.build_meta backend, an additional setup.cfg file is needed.
A minimal example would be:
[metadata] name = my-project version = 1.0.2 description = This is the short description long_description = file: path/to/my/long/description license = GPL author = John Doe author_email = [email protected] url = example.com/my-project [options] packages = my-project python_requires = >= 3.6 install_requires = toml >= 0.10.2 [options.entry_points] console_scripts = my-project-cli = my-project:main
You will note that this is highly duplicative of the below Project section.
Setuptools (Legacy)
With all of the above in place, it's possible to use a simple shim setup.py. This will enable setup.py install to continue to work.
import setuptools
if __name__ == "__main__":
setuptools.setup()
Project
This is the focus of PEP 621. It is more-or-less a direct mapping of a boilerplate setup.py file into the TOML format.
[project]
name = "my-project"
description = "This is the short description"
readme = "path/to/my/long/description"
version = "1.0.2"
authors = [ { name = "John Doe", email = "[email protected]" } ]
urls = { homepage = "example.com/my-project" }
license = { file = "path/to/my/license" }
requires-python = ">=3.6"
dependencies = [
"toml >= 0.10.1",
]
[project.scripts]
my-project-cli = "my-project:main"Some notable changes from setup.py:
long_description
a long standing practice was to read a project's README file and provide this as a long_description
now, just provide a path to the README file
author, author_email, maintainer, maintainer_email
authors and maintainers have replaced these
- this design greatly simplifies the specification of multiple individuals
license
while a license may continue to be provided as a string, the syntax has changed (license = { text = "GPL" })
- the current recommendation is to provide a path to the license file
- future PEPs may build on this design
entry_points
project.scripts exists as a more-or-less perfect mapping
an analogous [projects.gui-scripts] exists for scripts that should only be called in a graphical setting
Dependencies
PEP 631 furthered the design of dependencies and introduced optional-dependencies. This is the pyproject.toml of docker-compose:
[project] dependencies = [ 'cached-property >= 1.2.0, < 2', 'distro >= 1.5.0, < 2', 'docker[ssh] >= 4.2.2, < 5', 'dockerpty >= 0.4.1, < 1', 'docopt >= 0.6.1, < 1', 'jsonschema >= 2.5.1, < 4', 'PyYAML >= 3.10, < 6', 'python-dotenv >= 0.13.0, < 1', 'requests >= 2.20.0, < 3', 'texttable >= 0.9.0, < 2', 'websocket-client >= 0.32.0, < 1', # Conditional 'backports.shutil_get_terminal_size == 1.0.0; python_version < "3.3"', 'backports.ssl_match_hostname >= 3.5, < 4; python_version < "3.5"', 'colorama >= 0.4, < 1; sys_platform == "win32"', 'enum34 >= 1.0.4, < 2; python_version < "3.4"', 'ipaddress >= 1.0.16, < 2; python_version < "3.3"', 'subprocess32 >= 3.5.4, < 4; python_version < "3.2"', ] [project.optional-dependencies] socks = [ 'PySocks >= 1.5.6, != 1.5.7, < 2' ] tests = [ 'ddt >= 1.2.2, < 2', 'pytest < 6', 'mock >= 1.0.1, < 4; python_version < "3.4"', ]