How To Create A Python Package

Overview

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 file¹.

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

Use With setuptools

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

1
2
3

[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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

[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)².

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

1

$ 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 website³.

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:

1
2
3
4
5
6

[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:

1

$ pip install .[test]

References