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.14
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 defines a format for the description file, and a standard location for where to place it.
Location
When possible, Python installations should install the static description file
inside the standard library directory, with the name build-details.json
(Eg. /usr/lib/python3.14/build-details.json
).
Important
Given that there may be technical challenges, Python implementations are not required to provide the file if not feasable. In such scenarios, they may choose to provide it in a different maner.
Attention
Notwithstanding the standard location specified here, it does not prevent the file from additionally being provided in another location, and with a different name. In fact, the PEP authors expect future PEPs to define additional locations to install this file, for better discoverability.
Format
The format specification is defined by the JSON Schema definition provided below, which is rendered in an human-readable format here.
$schema |
https://json-schema.org/draft/2020-12/schema |
$id |
https://github.com/python/peps/blob/main/peps/pep-0739/python-build-info-v1.schema.json |
Title | Static description file for the build details of Python installations |
Type | object |
Additional properties | Not allowed |
schema_version
Type | string (constant — 1 ) |
Description | Schema version. This is a constant value and MUST be |
Required | True |
base_prefix
Type | string |
Description | Base prefix of the Python installation. Either an absolute path, or a relative path to directory where this file is contained. |
Examples | /usr , ../.. , etc. |
Required | False |
platform
Type | string |
Description | System platform string. This field SHOULD be equivalent to |
Examples |
|
Required | True |
language
Type | object |
Description | Object containing details related to the Python language
specification. In addition to the required keys, implementations may choose to include extra keys with implementation-specific details. |
Required | True |
Additional properties | Not allowed |
language.version
Type | string |
Description | String representation the Python language version — a version
string consisting only of the major and minor components. This field SHOULD be equivalent to
|
Examples | 3.14 , etc. |
Required | True |
implementation
Type | object |
Description | Object containing details related to Python implementation. This section SHOULD be equivalent to
|
Required | True |
Additional properties | Allowed |
implementation.name
Type | string |
Description | Lower-case name of the Python implementation. |
Examples | cpython , pypy , etc. |
Required | True |
implementation.version
Type | object |
Description | Object in the format of sys.version_info , containing
the implementation version. |
Examples |
|
Required | True |
Additional properties | Not allowed |
implementation.version.major
Type | number |
Required | True |
implementation.version.minor
Type | number |
Required | True |
implementation.version.micro
Type | number |
Required | True |
implementation.version.releaselevel
Type | string (enum — alpha , beta , candidate , final ) |
Required | True |
implementation.version.serial
Type | number |
Required | True |
interpreter
Type | object |
Description | Object containing details Python interpreter. This section MUST be present if the Python installation provides an interpreter binary, otherwise this section will be missing. |
Required | False |
Additional properties | Not allowed |
interpreter.path
Type | string |
Description | The path to the Python interprer. Either an absolute path, or a
relative path to the path defined in the base_prefix key. |
Examples |
|
Required | True |
abi
Type | object |
Description | Object containing details related to ABI. |
Required | False |
Additional properties | Not allowed |
abi.flags
Type | array |
Description | Build configuration flags, used to calculate the extension
suffix. The flags MUST be defined in the order they appear on the extension suffix. |
Examples | ['t', 'd'] , etc. |
Required | True |
abi.extension_suffix
Type | string |
Description | Suffix used for extensions built against the current
implementation version. This field MUST be present if the Python implementation supports extensions, otherwise this entry will be missing. |
Examples |
|
Required | True |
abi.stable_abi_suffix
Type | string |
Description | Suffix used for extensions built against the stable ABI. This field MUST be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing. |
Examples | .abi3.so , etc. |
Required | False |
suffixes
Type | object |
Description | Valid module suffixes grouped by type. This section SHOULD be equivalent to the
|
Examples |
|
Required | False |
Additional properties | Allowed |
libpython
Type | object |
Description | Object containing details related to the libpython library.This section MUST by present if Python installation provides a
|
Required | False |
Additional properties | Not allowed |
libpython.dynamic
Type | string |
Description | The path to the dynamic libpython library. Either an
absolute path, or a relative path to the path defined in the
base_prefix key.This field MUST be present if the Python installation provides a
dynamic |
Examples |
|
Required | False |
libpython.static
Type | string |
Description | The path to the static libpython library. Either an absolute
path, or a relative path to the path defined in the
base_prefix key.This field MUST be present if the Python installation provides a
static |
Examples |
|
Required | False |
libpython.link_to_libpython
Type | boolean |
Description | Should extensions built against a dynamic libpython link to
it?This field MUST be present if the Python installation provides a
dynamic |
Required | False |
c_api
Type | object |
Description | Object containing details related to the Python C API, if
available. This section MUST be present if the Python implementation provides a C API, otherwise this section will be missing. |
Required | False |
Additional properties | Not allowed |
c_api.headers
Type | string |
Description | The path to the C API headers. Either an absolute path, or a
relative path to the path defined in the base_prefix key. |
Examples |
|
Required | True |
c_api.pkgconfig_path
Type | string |
Description | The path to the pkg-config definition files. Either an absolute
path, or a relative path to the path defined in the
base_prefix key.This field MUST be present if the Python implementation provides pkg-config definition files for the C API, otherwise this section will be missing. |
Examples |
|
Required | False |
arbitrary_data
Type | object |
Description | Object containing extra arbitrary data. This is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implamentations may choose what data to provide in this section. |
Required | False |
Additional properties | Allowed |
Example
1{
2 "schema_version": "1",
3 "base_prefix": "/usr",
4 "platform": "linux-x86_64",
5 "language": {
6 "version": "3.14"
7 },
8 "implementation": {
9 "name": "cpython",
10 "version": {
11 "major": 3,
12 "minor": 14,
13 "micro": 0,
14 "releaselevel": "alpha",
15 "serial": 0
16 },
17 "hexversion": 51249312,
18 "cache_tag": "cpython-314",
19 "_multiarch": "x86_64-linux-gnu"
20 },
21 "interpreter": {
22 "path": "/usr/bin/python"
23 },
24 "abi": {
25 "flags": ["t", "d"],
26 "extension_suffix": ".cpython-314-x86_64-linux-gnu.so",
27 "stable_abi_suffix": ".abi3.so"
28 },
29 "suffixes": {
30 "source": [".py"],
31 "bytecode": [".pyc"],
32 "optimized_bytecode": [".pyc"],
33 "debug_bytecode": [".pyc"],
34 "extensions": [".cpython-314-x86_64-linux-gnu.so", ".abi3.so", ".so"]
35 },
36 "libpython": {
37 "dynamic": "/usr/lib/libpython3.14.so.1.0",
38 "static": "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
39 "link_to_libpython": true
40 },
41 "c_api": {
42 "headers": "/usr/include/python3.14",
43 "pkgconfig_path": "/usr/lib/pkgconfig"
44 }
45}
JSON Schema
1{
2 "$schema": "https://json-schema.org/draft/2020-12/schema",
3 "$id": "https://github.com/python/peps/blob/main/peps/pep-0739/python-build-info-v1.schema.json",
4 "type": "object",
5 "title": "Static description file for the build details of Python installations",
6 "required": [
7 "schema_version",
8 "platform",
9 "language",
10 "implementation"
11 ],
12 "additionalProperties": false,
13 "properties": {
14 "schema_version": {
15 "type": "string",
16 "description": "Schema version.\n\nThis is a constant value and MUST be ``1``, when using the schema described here. Future iterations of this schema MUST update this value.",
17 "const": "1"
18 },
19 "base_prefix": {
20 "type": "string",
21 "description": "Base prefix of the Python installation.\n\nEither an absolute path, or a relative path to directory where this file is contained.",
22 "examples": [
23 "/usr",
24 "../.."
25 ]
26 },
27 "platform": {
28 "type": "string",
29 "description": "System platform string.\n\nThis field SHOULD be equivalent to ``sysconfig.get_platform()``.",
30 "examples": [
31 "linux-x86_64"
32 ]
33 },
34 "language": {
35 "type": "object",
36 "description": "Object containing details related to the Python language specification.\n\nIn addition to the required keys, implementations may choose to include extra keys with implementation-specific details.",
37 "required": [
38 "version"
39 ],
40 "additionalProperties": false,
41 "properties": {
42 "version": {
43 "type": "string",
44 "description": "String representation the Python language version — a version string consisting only of the *major* and *minor* components.\n\nThis field SHOULD be equivalent to ``sysconfig.get_python_version()``.",
45 "examples": ["3.14"]
46 }
47 }
48 },
49 "implementation": {
50 "type": "object",
51 "description": "Object containing details related to Python implementation.\n\nThis section SHOULD be equivalent to :py:data:`sys.implementation`. It follows specification defined in PEP 421, meaning that on top of the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore.",
52 "required": [
53 "name",
54 "version",
55 "hexversion",
56 "cache_tag"
57 ],
58 "additionalProperties": true,
59 "properties": {
60 "name": {
61 "type": "string",
62 "description": "Lower-case name of the Python implementation.",
63 "examples": ["cpython", "pypy"]
64 },
65 "version": {
66 "type": "object",
67 "description": "Object in the format of :py:data:`sys.version_info`, containing the implementation version.",
68 "required": ["major", "minor", "micro", "releaselevel", "serial"],
69 "additionalProperties": false,
70 "examples": [
71 {
72 "major": 3,
73 "minor": 13,
74 "micro": 1,
75 "releaselevel": "final",
76 "serial": 0
77 },
78 {
79 "major": 7,
80 "minor": 3,
81 "micro": 16,
82 "releaselevel": "final",
83 "serial": 0
84 }
85 ],
86 "properties": {
87 "major": {
88 "type": "number"
89 },
90 "minor": {
91 "type": "number"
92 },
93 "micro": {
94 "type": "number"
95 },
96 "releaselevel": {
97 "type": "string",
98 "enum": ["alpha", "beta", "candidate", "final"]
99 },
100 "serial": {
101 "type": "number"
102 }
103 }
104 }
105 }
106 },
107 "interpreter": {
108 "type": "object",
109 "description": "Object containing details Python interpreter.\n\nThis section MUST be present if the Python installation provides an interpreter binary, otherwise this section will be missing.",
110 "required": [
111 "path"
112 ],
113 "additionalProperties": false,
114 "properties": {
115 "path": {
116 "type": "string",
117 "description": "The path to the Python interprer. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.",
118 "examples": [
119 "/usr/bin/python",
120 "bin/python"
121 ]
122 }
123 }
124 },
125 "abi": {
126 "type": "object",
127 "description": "Object containing details related to ABI.",
128 "required": [
129 "flags",
130 "extension_suffix"
131 ],
132 "additionalProperties": false,
133 "properties": {
134 "flags": {
135 "type": "array",
136 "description": "Build configuration flags, used to calculate the extension suffix.\n\nThe flags MUST be defined in the order they appear on the extension suffix.",
137 "additionalProperties": true,
138 "examples": [
139 ["t", "d"]
140 ]
141 },
142 "extension_suffix": {
143 "type": "string",
144 "description": "Suffix used for extensions built against the current implementation version.\n\nThis field MUST be present if the Python implementation supports extensions, otherwise this entry will be missing.",
145 "examples": [
146 ".cpython-314-x86_64-linux-gnu.so"
147 ]
148 },
149 "stable_abi_suffix": {
150 "type": "string",
151 "description": "Suffix used for extensions built against the stable ABI.\n\nThis field MUST be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing.",
152 "examples": [
153 ".abi3.so"
154 ]
155 }
156 }
157 },
158 "suffixes": {
159 "type": "object",
160 "description": "Valid module suffixes grouped by type.\n\nThis section SHOULD be equivalent to the ``importlib.machinery.*_SUFFIXES`` attributes, if the implementation provides such suffixes. However, if the Python implementation does not provide suffixes of the kind specified by any of the attributes, the equivalent sub-section is not required to be present. Additionally, if a Python implementation provides extension kinds other than the ones listed on ``importlib.machinery`` module, they MAY add a sub-section for them.",
161 "examples": [
162 {
163 "source": [".py"],
164 "bytecode": [".pyc"],
165 "optimized_bytecode": [".pyc"],
166 "debug_bytecode": [".pyc"],
167 "extensions": [".cpython-313-x86_64-linux-gnu.so", ".abi3.so", ".so"]
168 }
169 ]
170 },
171 "libpython": {
172 "type": "object",
173 "description": "Object containing details related to the ``libpython`` library.\n\nThis section MUST by present if Python installation provides a ``libpython`` library, otherwise this section will be missing.",
174 "additionalProperties": false,
175 "properties": {
176 "dynamic": {
177 "type": "string",
178 "description": "The path to the dynamic ``libpython`` library. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.\n\nThis field MUST be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing.",
179 "examples": [
180 "/usr/lib/libpython3.14.so.1.0",
181 "lib/libpython3.14.so.1.0"
182 ]
183 },
184 "static": {
185 "type": "string",
186 "description": "The path to the static ``libpython`` library. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.\n\nThis field MUST be present if the Python installation provides a static ``libpython`` library, otherwise this entry will be missing.",
187 "examples": [
188 "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
189 "lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a"
190 ]
191 },
192 "link_to_libpython": {
193 "type": "boolean",
194 "description": "Should extensions built against a dynamic ``libpython`` link to it?\n\nThis field MUST be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing."
195 }
196 }
197 },
198 "c_api": {
199 "type": "object",
200 "description": "Object containing details related to the Python C API, if available.\n\nThis section MUST be present if the Python implementation provides a C API, otherwise this section will be missing.",
201 "required": [
202 "headers"
203 ],
204 "additionalProperties": false,
205 "properties": {
206 "headers": {
207 "type": "string",
208 "description": "The path to the C API headers. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.",
209 "examples": [
210 "/usr/include/python3.14",
211 "include/python3.14"
212 ]
213 },
214 "pkgconfig_path": {
215 "type": "string",
216 "description": "The path to the pkg-config definition files. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.\n\nThis field MUST be present if the Python implementation provides pkg-config definition files for the C API, otherwise this section will be missing.",
217 "examples": [
218 "/usr/lib/pkgconfig",
219 "lib/pkgconfig"
220 ]
221 }
222 }
223 },
224 "arbitrary_data": {
225 "type": "object",
226 "description": "Object containing extra arbitrary data.\n\nThis is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implamentations may choose what data to provide in this section.",
227 "additionalProperties": true
228 }
229 }
230}
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 authors 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 across 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-09-12 02:43:59 GMT