Python: replace setup.py with pyproject.toml

Related: Minimal setup.py


pip ≥ 9.1 can use pyproject.toml instead of setup.py, for simpler syntax.

flit uses pyproject.toml for simpler PyPi uploads, and can also install programs (as alternative to pip). 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

  1. author: flit publish to PyPi
  2. end-user: python -m 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.com/username/yourprogram/archive/master.zip this downloads and installs the latest Git commit to master 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 and PEP 518

Minimal pyproject.toml

  1. assuming your package is named myprogram, have a directory structure like
    pyproject.toml
    myprogram/
        __init__.py
    
  2. ensure your __init__.py starts with a one-line description and version. You must increment this version for each PyPi upload (or use bumpversion).
    """My program is 2x faster and 1/3 the size of Hello World."""
    __version__ = '0.1.0'
    
  3. pyproject.toml contains something like:
    [build-system]
    requires = ["flit"]
    build-backend = "flit.buildapi"
    
    [tool.flit.metadata]
    module = "myprogram"
    author = "Author Name"
    author-email = "[email protected]"
    home-page = "https://github.com/username/reponame"
    
    requires=['numpy','matplotlib (>=2.1)']
    requires-python='>=3.4'
    
    description-file='README.rst'
    classifiers=[
    'Development Status :: 4 - Beta',
    'Programming Language :: Python']
    

PyPi upload

  1. Sign up for PyPi account. It may take several hours to get the confirmation email.
  2. create ~/.pypirc with the content
    [distutils]
    index-servers =
       pypi
    
    [pypi]
    repository=https://pypi.python.org/pypi
    username=<your pypi username>
    

    Note that I did NOT save my password for security.

  3. 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

python -m pip install myprogram

Notes

  • Obtain flit via
    python -m pip install flit
    
  • description-file must be .rst or .md format.
  • These old methods are superceded by the methods above.
    • python setup.py install python -m pip install .flit install
    • python setup.py develop python -m pip install -e .flit install -s
    • python setup.py sdist bdist_wheel uploadflit upload
  • flit reference
  • To my knowledge, f2py still needs setup.py, numpy.distutils and python -m pip install -e .

Leave a Comment