pyproject.tomlsetup.py based project?A specific kind ofBuilt Distribution that contains compiledextensions.
A library that takes a source treeand builds asource distribution orbuilt distribution from it.The build is delegated to the backend by afrontend.All backends offer a standardized interface.
Examples of build backends areflit’s flit-core,hatch’s hatchling,Maturin,meson-python,scikit-build-core,andSetuptools.
A tool that users might runthat takes arbitrary source trees orsource distributionsand builds source distributions orwheels from them.The actual building is delegated to each source tree’sbuild backend.
ADistribution format containing filesand metadata that only need to be moved to the correct location on thetarget system, to be installed.Wheel is such a format, whereasSource Distribution is not, in that it requires a build step before it can beinstalled. This format does not imply that Python files have to beprecompiled (Wheel intentionally does not include compiledPython files). SeePackage Formats for more information.
The concrete formCore Metadata takeswhen included inside an installedProject (METADATA file)or aDistribution Archive(PKG-INFO in aSdistandMETADATA in aWheel).
Thespecificationand the set ofCore Metadata Fields it definesthat describe key static attributes ofaDistribution Package orInstalled Project.
A single key-value pair(or sequence of such with the same name, for multiple-use fields)defined in theCore Metadata specand stored in theBuilt Metadata.Notably, distinct from aPyproject Metadata Key.
The physical distribution artifact (i.e. a file on disk)for aDistribution Package.
A versioned archive file that contains Pythonpackages,modules, and other resource files that areused to distribute aRelease. The archive file is what anend-user will download from the internet and install.
A distribution package is more commonly referred to with the singlewords “package” or “distribution”, but this guide may use the expandedterm when more clarity is needed to prevent confusion with anImport Package (which is also commonly called a “package”) oranother kind of distribution (e.g. a Linux distribution or the Pythonlanguage distribution), which are often referred to with the single term“distribution”. SeeDistribution package vs. import packagefor a breakdown of the differences.
ABuilt Distribution format introduced bySetuptools,which has been replaced byWheel. For details, seeWhat about eggs?.
AModule written in the low-level language of the Python implementation:C/C++ for Python, Java for Jython. Typically contained in a singledynamically loadable pre-compiled file, e.g. a shared object (.so) filefor Python extensions on Unix, a DLL (given the .pyd extension) forPython extensions on Windows, or a Java class file for Jythonextensions.
A Python module which can contain other modules or recursively, otherpackages.
An import package is more commonly referred to with the single word“package”, but this guide will use the expanded term when more clarityis needed to prevent confusion with aDistribution Package whichis also commonly called a “package”. SeeDistribution package vs. import packagefor a breakdown of the differences.
AProject that is installed for use witha Python interpreter orVirtual Environment,as described in the specificationRecording installed projects.
A set of distributions at specified versions which are compatible witheach other. Typically a test suite will be run which passes all testsbefore a specific set of packages is declared a known good set. Thisterm is commonly used by frameworks and toolkits which are comprised ofmultiple individual distributions.
A PyPI Trove classifier(asdescribedin theCore Metadata specification)which begins withLicense::.
A string with valid SPDX license expression syntax,including one or more SPDXLicense Identifier(s),which describes aDistribution Archive’s license(s)and how they inter-relate.Examples:GPL-3.0-or-later,MITAND(Apache-2.0ORBSD-2-Clause)
A valid SPDX short-form license identifier,originally specified inPEP 639.This includes all valid SPDX identifiers andthe customLicenseRef-[idstring] strings conforming to theSPDX specification.Examples:MIT,GPL-3.0-only,LicenseRef-My-Custom-License
The basic unit of code reusability in Python, existing in one of twotypes:Pure Module, orExtension Module.
A repository of distributions with a web interface to automatepackage discovery and consumption.
A private or other non-canonicalPackage Index indicated bya specificProject as the index preferred or required toresolve dependencies of that project.
A library, framework, script, plugin, application, or collection of dataor other resources, or some combination thereof that is intended to bepackaged into aDistribution.
Since most projects createDistributionsusing eitherPEP 518build-system,distutils orSetuptools, another practical way to define projects currentlyis something that contains apyproject.toml,setup.py,orsetup.cfg file at the root of the project source directory.
Python projects must have unique names, which are registered onPyPI. Each project will thencontain one or moreReleases, and each release maycomprise one or moredistributions.
Note that there is a strong convention to name a project after the nameof the package that is imported to run that project. However, thisdoesn’t have to hold true. It’s possible to install a distribution fromthe project ‘foo’ and have it provide a package importable only as‘bar’.
The filesystem directory in whichaProject’ssource tree is located.
The on-disk format of aProject used for development,containing its raw source code before being packagedinto aSource DistributionorBuilt Distribution.
Metadata defined by the package authorin aProject’ssource tree,to be transformed intoCore Metadata fieldsin theBuilt Metadataby the project’sbuild backend.Can be written asPyproject Metadata,or in a tool-specific format(under the[tool] table inpyproject.toml,or in a tool’s own configuration file).
AModule written in Python and contained in a single.py file (andpossibly associated.pyc and/or.pyo files).
TheProject Source Metadata formatdefined by thepyproject.toml specification specificationand originally introduced inPEP 621,stored asPyproject Metadata Keysunder the[project] table of apyproject.toml file.Notably,not a tool-specific source metadata formatunder the[tool] table inpyproject.toml.
A top-level TOML key in the[project] table inpyproject.toml;part of thePyproject Metadata.Notably, distinct from aCore Metadata Field.
A second-level TOML key under a table-valuedPyproject Metadata Key.
PyPA is a working group that maintains many of the relevantprojects in Python packaging. They maintain a site atpypa.io, host projects onGitHub andBitbucket, and discuss issues on thedistutils-sig mailing listandthe Python Discourse forum.
PyPI is the defaultPackageIndex for the Python community. It is open to all Python developers toconsume and distribute their distributions.
pypi.org is the domain name for thePython Package Index (PyPI). It replaced the legacy indexdomain name,pypi.python.org, in 2017. It is powered byWarehouse.
The tool-agnosticProject specification file.Defined inPEP 518.
A snapshot of aProject at a particular point in time, denotedby a version identifier.
Making a release may entail the publishing of multipleDistributions. For example, if version1.0 of a project was released, it could be available in both a sourcedistribution format and a Windows installer distribution format.
A specification for apackage to beinstalled.pip, thePYPA recommended installer, allows various forms of specificationthat can all be considered a “requirement”. For more information, see thepip install reference.
A format used bypip to install packages from aPackageIndex. For an EBNF diagram of the format, seeDependency specifiers.For example, “foo>=1.3” is arequirement specifier, where “foo” is the project name, and the “>=1.3”portion is theVersion Specifier
A file containing a list ofRequirements that canbe installed usingpip. For more information, see thepipdocs onRequirements Files.
The directory under which license files are stored in aProject Source Tree,Distribution ArchiveorInstalled Project.For aProject Source Tree orSource Distribution (or “sdist”), this is theProject Root Directory.For aBuilt Distribution orInstalled Project,this is the.dist-info/licenses/ directory ofthe wheel archive or project folder respectively.Also, the root directory that pathsrecorded in theLicense-FileCore Metadata Field are relative to.
The project specification files fordistutils andSetuptools.See alsopyproject.toml.
An archive containing the raw source code for aRelease, priorto creation of aSource Distribution orBuilt Distribution.
Adistribution format (usually generatedusingpython-mbuild--sdist) that provides metadata and theessential source files needed for installing by a tool likepip,or for generating aBuilt Distribution. SeePackage Formatsfor more information.
A package provided in a format native to the operating system,e.g. an rpm or dpkg file.
The version component of aRequirement Specifier. For example,the “>=1.3” portion of “foo>=1.3”. Read theVersion specifier specification for a full description of thespecifiers that Python packaging currently supports. Support for thisspecification was implemented inSetuptools v8.0 andpip v6.0.
An isolated Python environment that allows packages to be installed foruse by a particular application, rather than being installed systemwide. For more information, see the section onCreating Virtual Environments.
The standardBuilt Distribution formatoriginally introduced inPEP 427and defined by theBinary distribution format specification.SeePackage Formats for more information.Not to be confused with its reference implementation,theWheel Project.
The PyPA reference implementation of theWheel Format; seewheel.
A collection ofdistributions availablefor importing. These are the distributions that are on thesys.pathvariable. At most, oneDistribution for aproject is possible in a working set.