Glossary - Python Packaging User Guide
Skip to content Back to top View this page Edit this page Glossary ¶ Binary Distribution ¶ A specific kind of Built Distribution that contains compiled extensions. Build Backend ¶ A library that takes a source tree and builds a source distribution or built distribution from it. The build is delegated to the backend by a frontend . All backends offer a standardized interface. Examples of build backends are flit’s flit-core , hatch’s hatchling , Maturin , meson-python , scikit-build-core , and Setuptools .
Build Frontend ¶ A tool that users might run that takes arbitrary source trees or source distributions and builds source distributions or wheels from them. The actual building is delegated to each source tree’s build backend . Examples of build frontends are pip and build . Built Distribution ¶ A Distribution format containing files and metadata that only need to be moved to the correct location on the target system, to be installed.
Wheel is such a format, whereas Source Distribution is not, in that it requires a build step before it can be installed. This format does not imply that Python files have to be precompiled ( Wheel intentionally does not include compiled Python files). See Package Formats for more information. Built Metadata ¶ The concrete form Core Metadata takes when included inside an installed Project ( METADATA file) or a Distribution Archive ( PKG-INFO in a Sdist and METADATA in a Wheel ).
Core Metadata ¶ The specification and the set of Core Metadata Field s it defines that describe key static attributes of a Distribution Package or Installed Project . Core Metadata Field ¶ A single key-value pair (or sequence of such with the same name, for multiple-use fields) defined in the Core Metadata spec and stored in the Built Metadata . Notably, distinct from a Pyproject Metadata Key . Distribution Archive ¶ The physical distribution artifact (i.e. a file on disk) for a Distribution Package .
Distribution Package ¶ A versioned archive file that contains Python packages , modules , and other resource files that are used to distribute a Release . The archive file is what an end-user will download from the internet and install. A distribution package is more commonly referred to with the single words “package” or “distribution”, but this guide may use the expanded term when more clarity is needed to prevent confusion with an Import Package (which is also commonly called a “package”) or another kind of distribution (e.g. a Linux distribution or the Python language distribution), which are often referred to with the single term “distribution”.
See Distribution package vs. import package for a breakdown of the differences. Egg ¶ A Built Distribution format introduced by Setuptools , which has been replaced by Wheel . For details, see What about eggs? . Extension Module ¶ A Module written in the low-level language of the Python implementation: C/C++ for Python, Java for Jython. Typically contained in a single dynamically loadable pre-compiled file, e.g. a shared object (.so) file for Python extensions on Unix, a DLL (given the .pyd extension) for Python extensions on Windows, or a Java class file for Jython extensions.
Import Package ¶ A Python module which can contain other modules or recursively, other packages. An import package is more commonly referred to with the single word “package”, but this guide will use the expanded term when more clarity is needed to prevent confusion with a Distribution Package which is also commonly called a “package”. See Distribution package vs. import package for a breakdown of the differences.
Installed Project ¶ A Project that is installed for use with a Python interpreter or Virtual Environment , as described in the specification Recording installed projects . Known Good Set (KGS) ¶ A set of distributions at specified versions which are compatible with each other. Typically a test suite will be run which passes all tests before a specific set of packages is declared a known good set. This term is commonly used by frameworks and toolkits which are comprised of multiple individual distributions.
License Classifier ¶ A PyPI Trove classifier (as described in the Core Metadata specification) which begins with License :: . License Expression ¶ SPDX Expression ¶ A string with valid SPDX license expression syntax, including one or more SPDX License Identifier (s), which describes a Distribution Archive ’s license(s) and how they inter-relate. Examples: GPL-3.0-or-later , MIT AND (Apache-2.0 OR BSD-2-Clause) License Identifier ¶ SPDX Identifier ¶ A valid SPDX short-form license identifier, originally specified in PEP 639 .
This includes all valid SPDX identifiers and the custom LicenseRef-[idstring] strings conforming to the SPDX specification. Examples: MIT , GPL-3.0-only , LicenseRef-My-Custom-License Module ¶ The basic unit of code reusability in Python, existing in one of two types: Pure Module , or Extension Module . Namespace Package ¶ A mechanism for splitting a single Import Package across one or more Distribution Packages . For guidance on creating namespace packages, see Packaging namespace packages .
Package Index ¶ A repository of distributions with a web interface to automate package discovery and consumption. Per Project Index ¶ A private or other non-canonical Package Index indicated by a specific Project as the index preferred or required to resolve dependencies of that project. Project ¶ A named collection of software or other resources that is developed and released as a unit, such as a library, application, or plugin.
The project’s files are maintained in a Project Source Tree . Each Release is a version of the project and may comprise one or more distribution packages , such as a Source Distribution (or “sdist”) and a Wheel . When a project is published on a Package Index such as PyPI , its name must be unique within that index. Note that there is a strong convention to name a project after the name of the package that is imported to run that project.
However, this doesn’t have to hold true. It’s possible to install a distribution from the project ‘foo’ and have it provide a package importable only as ‘bar’. Project Root Directory ¶ The filesystem directory in which a Project ’s source tree is located. Project Source Tree ¶ The on-disk format of a Project used for development, containing its raw source code before being packaged into a Source Distribution or Built Distribution .
Project Source Metadata ¶ Metadata defined by the package author in a Project ’s source tree , to be transformed into Core Metadata field s in the Built Metadata by the project’s build backend . Can be written as Pyproject Metadata , or in a tool-specific format (under the [tool] table in pyproject.toml , or in a tool’s own configuration file). Pure Module ¶ A Module written in Python and contained in a single .py file (and possibly associated .pyc and/or .pyo files).
Pyproject Metadata ¶ The Project Source Metadata format defined by the pyproject.toml specification specification and originally introduced in PEP 621 , stored as Pyproject Metadata Key s under the [project] table of a pyproject.toml file. Notably, not a tool-specific source metadata format under the [tool] table in pyproject.toml . Pyproject Metadata Key ¶ A top-level TOML key in the [project] table in pyproject.toml ; part of the Pyproject Metadata .
Notably, distinct from a Core Metadata Field . Pyproject Metadata Subkey ¶ A second-level TOML key under a table-valued Pyproject Metadata Key . Python Packaging Authority (PyPA) ¶ PyPA is a working group that maintains many of the relevant projects in Python packaging. They maintain a site at pypa.io , host projects on GitHub , and discuss issues on the distutils-sig mailing list and the Python Discourse forum . Python Package Index (PyPI) ¶ PyPI is the default Package Index for the Python community.
It is open to all
The rest of this page is on the live site.