Augment/replace setup.py with pyproject.toml
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
- author:
flit publish
to PyPI - end-user:
pip install yourprogram
this usespyproject.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 tomain
branch (or other branch or release version they choose) - developer-user:
git clone
your repo and install in develop mode byflit install -s
. This puts a symbolic link to your local Git directory (where yougit clone
’d).
This standard was defined in
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']
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
viapip 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
f2py
still needssetup.py