PEP 739 – Static description file for build details of Python installations
- Author:
- Filipe Laíns <lains at riseup.net>
- PEP-Delegate:
- Paul Moore <p.f.moore at gmail.com>
- Discussions-To:
- Discourse thread
- Status:
- Draft
- Type:
- Standards Track
- Topic:
- Packaging
- Created:
- 19-Dec-2023
- Python-Version:
- 3.13
Abstract
Introduce a standard format for a static description file with build details of Python installations.
Rationale
When introspecting a Python installation, running code is often undesirable or impossible. Having a static description file makes various of Python build details available without having to run the interpreter.
This is helpful for use-cases such as cross-compilation, Python launchers, etc.
Scope
This PEP only defines a format. Python implementations may choose to include a build details file as part of their distribution, but they are not required to, and the specifics of how that file is provided are completely up to them.
Specification
The standard Python build description format consists of the JSON representation of a dictionary with the with the following keys.
schema_version
- Type:
number
- Description:
- Version of the schema to parse the file contents. It SHOULD be
1
for the format described in this document. Future versions MAY add, remove, or change fields. Versions that only add fields MAY choose to only increment the schema version by a decimal point.
language
Subsection with details related to the Python language specification.
version
- Type:
string
- Description:
- String representation the Python language version — a version
string consisting only of the major and minor components (Eg.
3.13
).
implementation
Subsection with details related to Python implementation. This section SHOULD be
equivalent to sys.implementation
on most implementations, but only
the name
and version
keys are actually required to be present.
name
- Type:
string
- Description:
- Lower-case name of the Python implementation.
version
- Type:
object
- Description:
- Object in the format of
sys.version_info
, containing the implementation version.
Implementation-specific keys
Additionally to the keys defined above, implementations may choose to include extra keys with extra implementation-specific details.
interpreter
Subsection with details Python interpreter. If the Python installation does not provide an interpreter, this section will be missing.
path
- Type:
string
- Description:
- The path to the Python interprer. Either an absolute path, or a relative path to the directory containing this file, if applicable.
libpython
Subsection with details related to the libpython
library. If the Python
installation does not provide a libpython
library, this section will be
missing.
dynamic
- Type:
string
- Description:
- The path to the dynamic
libpython
library. Either an absolute path, or a relative path to the directory containing this file, if applicable. If the Python installation does not provide a dynamiclibpython
library, this entry will be missing.
static
- Type:
string
- Description:
- The path to the static
libpython
library. Either an absolute path, or a relative path to the directory containing this file, if applicable. If the Python installation does not provide a staticlibpython
library, this entry will be missing.
c_api
Subsection with details related to the Python C API, if available. If the Python implementation does not provide a C API, this section will be missing.
headers
- Type:
string
- Description:
- The path to the C API headers. Either an absolute path, or a relative path to the directory containing this file, if applicable.
Example
{
"schema_version": 1,
"language": {
"version": "3.13"
},
"implementation": {
"name": "cpython",
"version": {
"major": 3,
"minor": 13,
"micro": 1,
"releaselevel": "final",
"serial": 0
},
"hexversion": 51184112,
"cache_tag": "cpython-313",
"_multiarch": "x86_64-linux-gnu"
},
"libpython": {
"dynamic": "/usr/lib/libpython3.13.so.1.0",
"static": "/usr/lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a",
},
"c_api": {
"headers": "/usr/include/python3.13"
}
}
Rejected Ideas
Having a larger scope
One of the main requests in the discussion of this PEP was the inclusion of
other kind of information, such as the site-packages
path. It is the opinion
of the PEP author that information regarding the Python environment should be
provided by a separate file, creating the a clear separation between the build
details, which should be immutable accross any interpreter instance, and details
that can change, such as environment details.
Copyright
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
Source: https://github.com/python/peps/blob/main/peps/pep-0739.rst
Last modified: 2024-03-13 13:01:38 GMT