Skip to content
mbedded.ninja

How To Create A Python Package

Authors:
Geoffrey Hunter
Geoffrey Hunter
Published On:
May 2, 2023
Last Updated:
May 9, 2023

PEP 621 introduced the pyproject.toml method of specifying package metadata, including how to build the package. The idea is that this method supports many different build systems, with the exact build system being mentioned under the [build-system] table inside the TOML file1.

The three main build systems that are supported as of 2023 are Setuptools, Flit and Poetry1.

Use With setuptools

You can specify you want to use Setuptools in the pyproject.toml by specifying the following under the [build-system] table:

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

A full, basic example of a pyproject.toml that tells pip to use setuptools to build the package:

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"


[project]
name = "my_package"
authors = [
    {name = "My name", email = "[email protected]"},
]
description = "My package description."
readme = "README.md"
requires-python = ">=3.7"
dependencies = [
  "PyYAML ~= 5.0",
  "requests >= 2.20.0, < 3",
]

If you specify the build metadata this way, you DO NOT need to add the setup.py Python file that setuptools traditionally required.

Note that dependencies are not pulled from a requirements.txt file, instead you have to list them in the pyproject.toml file under project.dependencies. PEP 631 specifies how to write these dependencies (this PEP has been merged into the overarching PEP 621)2.

Once this file is in place, you should be able to run a test installation by pointing pip at this package on the local file system, e.g.:

Terminal window
$ pip install /path/to/package/

where /path/to/package/ is the path to the directory in where the pyproject.toml resides.

For more information on using Setuptools with pyproject.toml, see the great documentation Configuring setuptools using pyproject.toml files on the Setuptools website3.

Optional Dependencies

You can add optional dependencies under a [project.optional-dependencies] table in the pyproject.toml file. One common use case is when you have a set of dependencies that are only required to run unit tests, but not when deploying the application to others.

Here is an example which adds three optional “test” dependencies:

[project.optional-dependencies]
test = [
    "mypy==0.910",
    "pytest==6.2.5",
    "pytest-cov==3.0.0",
]

These optional dependencies can be installed (along with the required dependencies) with:

Terminal window
$ pip install .[test]

References

Footnotes

  1. Python (2022, Oct 7). PEP 621 – Storing project metadata in pyproject.toml. Retrieved 2023-05-02, from https://peps.python.org/pep-0621/. ↩ ↩2

  2. Python (2022, Jun 14). PEP 631 – Dependency specification in pyproject.toml based on PEP 508. Retrieved 2023-05-02, from https://peps.python.org/pep-0631/. ↩

  3. Python Packaging Authority. Configuring setuptools using pyproject.toml files. Setuptools. Retrieved 2023-05-09, from https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html. ↩