Glossary
Binary Distribution ¶
A specific kind of that contains compiled extensions.
Build Backend ¶
A library that takes a source tree and builds a or from it. The build is delegated to the backend by a. 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 orand builds source distributions or from them. The actual building is delegated to each source tree’s.
Examples of build frontends are pip and build.
Built Distribution ¶
A format containing files and metadata that only need to be moved to the correct location on the target system, to be installed. is such a format, whereas 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 ( intentionally does not include compiled Python files). See Package Formats for more information.
The concrete form takes when included inside an installed (METADATA file) or a (PKG-INFO in aand METADATA in a ).
The specification and the set of s it defines that describe key static attributes of a or .
A single key-value pair (or sequence of such with the same name, for multiple-use fields) defined in the spec and stored in the . Notably, distinct from a .
Distribution Archive ¶
The physical distribution artifact (i.e. a file on disk) for a .
Distribution Package ¶
A versioned archive file that contains Python , , and other resource files that are used to distribute a . 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 (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 format introduced by Setuptools, which has been replaced by . For details, see What about eggs?.
Extension Module ¶
A 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 which is also commonly called a “package”. See Distribution package vs. import package for a breakdown of the differences.
Installed Project ¶
A that is installed for use with a Python interpreter or , 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.
A PyPI Trove classifier (as described in the specification) which begins with License ::.
SPDX Expression ¶
A string with valid SPDX license expression syntax, including one or more SPDX (s), which describes a ’s license(s) and how they inter-relate. Examples:GPL-3.0-or-later,MIT AND (Apache-2.0 OR BSD-2-Clause)
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: , or .
Package Index ¶
A repository of distributions with a web interface to automate discovery and consumption.
Per Project Index ¶
A private or other non-canonical indicated by a specific as the index preferred or required to resolve dependencies of that project.
Project ¶
A library, framework, script, plugin, application, or collection of data or other resources, or some combination thereof that is intended to be packaged into a .
Since most projects create using either PEP 518 build-system, distutils or Setuptools, another practical way to define projects currently is something that contains a , , or file at the root of the project source directory.
Python projects must have unique names, which are registered on. Each project will then contain one or more , and each release may comprise one or more .
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 ’s is located.
Project Source Tree ¶
The on-disk format of a used for development, containing its raw source code before being packaged into aor .
Metadata defined by the package author in a ’s , to be transformed into s in the by the project’s . Can be written as , or in a tool-specific format (under the [tool] table in pyproject.toml, or in a tool’s own configuration file).
Pure Module ¶
A written in Python and contained in a single .py file (and possibly associated .pyc and/or .pyo files).
The format defined by the pyproject.toml specification specification and originally introduced in PEP 621, stored as s under the [project] table of a file. Notably, not a tool-specific source metadata format under the [tool] table in pyproject.toml.
A top-level TOML key in the [project] table in pyproject.toml; part of the . Notably, distinct from a .
A second-level TOML key under a table-valued.
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 Bitbucket, and discuss issues on the distutils-sig mailing list and the Python Discourse forum.
Python Package Index (PyPI) ¶
PyPI is the default for the Python community. It is open to all Python developers to consume and distribute their distributions.
pypi.org ¶
pypi.org is the domain name for the. It replaced the legacy index domain name, pypi.python.org, in 2017. It is powered by Warehouse.
pyproject.toml ¶
The tool-agnostic specification file. Defined in PEP 518.
Release ¶
A snapshot of a at a particular point in time, denoted by a version identifier.
Making a release may entail the publishing of multiple. For example, if version 1.0 of a project was released, it could be available in both a source distribution format and a Windows installer distribution format.
Requirement ¶
A specification for a to be installed. pip, the recommended installer, allows various forms of specification that can all be considered a “requirement”. For more information, see the pip install reference.
Requirement Specifier ¶
A format used by pip to install packages from a . For an EBNF diagram of the format, see Dependency specifiers. For example, “foo>=1.3” is a requirement specifier, where “foo” is the project name, and the “>=1.3” portion is the
Requirements File ¶
A file containing a list of that can be installed using pip. For more information, see the pip docs on Requirements Files.
The directory under which license files are stored in a, or . For a or, this is the. For a or , this is the .dist-info/licenses/ directory of the wheel archive or project folder respectively. Also, the root directory that paths recorded in the License-File are relative to.
setup.py ¶
setup.cfg ¶
The project specification files for distutils and Setuptools. See also .
Source Archive ¶
An archive containing the raw source code for a , prior to creation of a or .
Source Distribution (or “sdist”) ¶
A format (usually generated using python -m build --sdist) that provides metadata and the essential source files needed for installing by a tool like pip, or for generating a . See Package Formats for more information.
System Package ¶
A package provided in a format native to the operating system, e.g. an rpm or dpkg file.
Version Specifier ¶
The version component of a . For example, the “>=1.3” portion of “foo>=1.3”. Read the Version specifier specification for a full description of the specifiers that Python packaging currently supports. Support for this specification was implemented in Setuptools v8.0 and pip v6.0.
Virtual Environment ¶
An isolated Python environment that allows packages to be installed for use by a particular application, rather than being installed system wide. For more information, see the section on Creating Virtual Environments.
Wheel Format ¶
Wheel ¶
The standard format originally introduced in PEP 427 and defined by the Binary distribution format specification. See Package Formats for more information. Not to be confused with its reference implementation, the .
Wheel Project ¶
The PyPA reference implementation of the ; see wheel.
Working Set ¶
A collection of available for importing. These are the distributions that are on the sys.path variable. At most, one for a project is possible in a working set.