pip ≥ 10 can use pyproject.toml instead of (or more commonly, along with) setup.py, for simpler syntax. pyproject.toml is particularly useful for f2py programs where Numpy must be installed before running setup.py install.

flit uses pyproject.toml for simpler PyPI uploads, and can also install programs (as alternative to pip), even without setup.py. End users can simply flit installfrom Github, without needing to git clone or use PyPI (unless they want to). flit and pyproject.toml lower Python program distribution difficulty for developers who don’t want to mess with PyPI, but also make it easier for those who do use PyPI.

Example: f2py

This example uses pyproject.toml to augment setup.py by first installing Numpy. Note: setup_requires in setup.cfg or setup.py is not recommended as it will cause offline (not internect-connected) systems to error on installing the Python package.

pyproject.toml:

[build-system]
requires = ["setuptools", "numpy"]

setup.py is constructed as usual, and when doing pip install -e . or pip install mypkg, Numpy will be installed first so that f2py or other Numpy-based extension modules can be built. A real-life example of this is in Lowtran

Example: pyproject.toml instead of setup.py

1. author: flit publish to PyPI
2. end-user: pip install yourprogram this uses pyproject.toml alone to install.

Users can also install from local or remote Git repos:

• end-user: flit installfrom https://github.invalid/username/yourprogram/archive/main.zip this downloads and installs the latest Git commit to main branch (or other branch or release version they choose)
• developer-user: git clone your repo and install in develop mode by flit install -s. This puts a symbolic link to your local Git directory (where you git clone’d).

This standard was defined in

• PEP 517
• PEP 518

Minimal pyproject.toml

Assuming your package is named myprogram, have a directory structure like

pyproject.toml
myprogram/
   __init__.py

Ensure __init__.py starts with a one-line description and version. You must increment this version for each PyPI upload (or use bumpversion).

"""Module docstring text"""
__version__ = '0.1.0'

pyproject.toml contains something like:

[build-system]
requires = ["flit"]
build-backend = "flit.buildapi"

[tool.flit.metadata]
module = "myprogram"
author = "Author Name"
author-email = "username@users.noreply.github.com"
home-page = "https://github.com/username/reponame"

requires=['numpy', 'matplotlib (>=2.1)']
requires-python='>=3.6'

description-file='README.md'
classifiers=[
'Development Status :: 4 - Beta',
'Programming Language :: Python']

• Trove Classifiers

PyPI upload

Sign up for PyPI account. It may take several hours to get the confirmation email.

Create ~/.pypirc with the content

[pypi]
username=pypiusername

Do NOT save password for security.

In your Python package directory that you want to upload

flit upload

Now your package is live to the world on PyPI. Anyone can install it via

pip install myprogram

Notes

• Obtain flit via

  pip install flit
  

• description-file must be .rst or .md format.

• These methods are superseded by the methods above.

  • python setup.py install pip install . → flit install
  • python setup.py develop pip install -e . → flit install -s
  • python setup.py sdist bdist_wheel upload → flit upload

• flit reference

• f2py still needs setup.py

• Python-only project should use flit

Related

Minimal setup.py