Important
This PEP is a historical document. The up-to-date, canonical spec,Recording installed projects, is maintained on thePyPA specs page.
×
See thePyPA specification update process for how to propose changes.
This PEP clarifies and updatesPEP 376 (Database of Installed PythonDistributions), rewriting it as an interoperability standard.It moves the canonical location of the standard to the PythonPackaging Authority (PyPA) standards repository, and sets up guidelinesfor changing it.
Two files in installed.dist-info directories are made optional:RECORD (whichPEP 376 lists as mandatory, but suggests it can be left outfor “system packages”), andINSTALLER.
Python packaging is moving from relying on specific tools (Setuptools and pip)toward an ecosystem of tools and tool-agnostic interoperability standards.
PEP 376 is not written as an interoperability standard.It describes implementation details of specific tools and libraries,and is underspecified, leaving much room for implementation-defined behavior.
This is a proposal to “distill” the standard fromPEP 376, clarify it,and rewrite it to be tool-agnostic.
The aim of this PEP is to have a better standard, not necessarily a perfect one.Some issues are left to later clarification.
PEP 376’s rationale focuses on two problems:
The new document focuses only the on-disk format of information aboutinstalled projects.Providing API to install, uninstall or query this information is left tobe implemented by tools.
The canonical standard forRecording installed projects (previously known asDatabase of Installed Python Distributions) is thedocumentation atpackaging.python.org.Any changes to the document (except trivial language or typography fixes) mustbe made through the PEP process.
The document is normative (with examples to aid understanding).PEPs that change it, such as this one, contain additional information that isexpected to get out of date, such as rationales and compatibilityconsiderations.
The proposed standard is submitted together with this PEP as a pull request topackaging.python.org.
The standard is renamed fromDatabase of Installed Python DistributionstoRecording installed projects.
While putting files in known locations on disk may be thought of asa “database”, it’s not what most people think about when they hear the term.The PyPA links toPEP 376 under the headingRecording installed distributions.
The PyPA glossary defines “Distribution” (or, “Distribution Package” to preventconfusion with e.g. Linux distributions) as “A versioned archive file […]”.Since there may be other ways to install Python code than from archive files,the document uses “installed project” rather than “installed distribution”.
All tool- and library-specific details are removed.The mechanisms of how a project is installed are also left out: the documentfocuses on the end state.One exception is a sketch of an uninstallation algorithm,which is given to better explain the purpose of theRECORD file.
References to.egg-info and.egg,formats specific tosetuptools anddistutils,are left out.
The.dist-info directory is allowed to contain files not specified inthe spec.The current tools already do this.
A note in the specification mentions files in the.dist-info directory ofwheels.Current tools copy these files to the installed.dist-info—somethingto keep in mind for further standardization efforts.
RECORD FileThe CSV dialect is specified to be the default of Python’scsv module.This resolves edge cases around handling double-quotes and line terminatorsin file names.
The “base” of relative paths inRECORD is specified relative to the.dist-info directory, rather than tool-specific--install-lib and--prefix options.
Bothhash andsize fields are now optional (for any file, not just.pyc,.pyo andRECORD). Leavng them out is discouraged,except for*.pyc andRECORD itself.(Note thatPEP 376 is unclear on what was optional; when taken literally,its text and examples contradict. Despite that, “both fields are optional“ is areasonable interpretation ofPEP 376.The alternative would be to mandate—rather than recommend—which files can berecorded without hash and size, and to update that list over time as new usecases come up.)
The new spec explicitly says that theRECORD file must now includeallfiles of the installed project (the exception for.pyc files remains).Since tools useRECORD for uninstallation, incomplete file lists couldintroduce orphaned files to users’ environments.On the other hand, this means that there is no way to record hashes of someany files if the full list of files is unknown.
A sketch of an uninstallation algorithm is included to clarify the file’sprimary purpose and contents.
Tools must not uninstall/remove projects that lack aRECORD file(unless they have external information, such as in system packagemanagers of Linux distros).
On Windows, files inRECORD may be separated by either/ or\.PEP 376 was unclear on this: it mandates forward slashes in one place, butshows backslackes in a Windows-specific example.
RECORD FileTheRECORD file is made optional.Not all tools can easily generate a list of installed files in aPython-specific format.
Specifically, theRECORD file is unnecessary when projects are installedby a Linux system packaging system, which has its own ways to keep track offiles, uninstall them or check their integrity.Having to keep aRECORD file in sync with the disk and the system packagedatabase would be unreasonably fragile, and noRECORD file is betterthan one that does not correspond to reality.
(Full disclosure: The author of this PEP is an RPM packager active in the Fedora Linux distro.)
INSTALLER FileTheINSTALLER file is also made optional, and specified to be used forinformational purposes only.It is still a single-line text file containing the name of the installer.
This file was originally added to distinguish projects installed by the Pythoninstaller (pip) from ones installed by other package managers(e.g.dnf).There were attempts to use this file to preventpip from updating oruninstalling packages it didn’t install.
Our goal is supporting interoperating tools, and basing any action onwhich tool happened to install a package runs counter to that goal.
Instead of relying on the installer name, tools should use feature detection.The current document offers a crude way of making a project untouchable byPython tooling: omittingRECORD file.
On the other hand, the installer name may be useful in hints to the user.
To align with this new purpose of the file, the new specification allowsany ASCII string inINSTALLER, rather than a lowercase identifier.It also suggests using the command-line command, if available.
REQUESTED File: Removed from SpecTheREQUESTED file is now considered a tool-specific extension.
PerPEP 376,REQUESTED was to be written when a project was installedby direct user request, as opposed to automatically to satisfy dependenciesof another project. Projects without this marker file could be uninstalledwhen no longer needed.
Despite the standard, many existing installers (including older versions ofpip) never write this file. There is no distinction between projectsthat are “OK to remove when no longer needed” and ones simply installed bya tool that ignoresREQUESTED. So, the file is currently not usable for itsintended purpose (unless a tool can use additional, non-standard information).
When possible, terms (such asname andversion) are qualified byreferences to existing specs.
To limit the scope of this PEP, some improvements are explicitly left tofuture PEPs:
RECORD file.dist-infoThis document is placed in the public domain or under theCC0-1.0-Universal license, whichever is more permissive.
Source:https://github.com/python/peps/blob/main/peps/pep-0627.rst
Last modified:2025-02-01 08:55:40 GMT