How To Create A Python Package

Contents

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

A 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 = "my_email@abc.com"},
]
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.

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