Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python Enhancement Proposals

PEP 739 – build-details.json 1.0 — a static description file for Python build details

Author:
Filipe Laíns <lains at python.org>
PEP-Delegate:
Paul Moore <p.f.moore at gmail.com>
Discussions-To:
Discourse thread
Status:
Accepted
Type:
Standards Track
Topic:
Packaging
Created:
19-Dec-2023
Python-Version:
3.14
Resolution:
Discourse message

Table of Contents

Abstract

This PEP introduces build-details.json, a static description file containing build details of Python installations.

It includes the definition of version 1.0 of the file format, and defines the standard location for this file.

Rationale

When introspecting a Python installation, running code is often undesirable or impossible. Having a static description file makes various build details of the Python installation available without having to run the interpreter.

This is helpful for use-cases such as cross-compilation, Python launchers, etc.

Scope

build-details.json is an installation-wide file, meaning that it MUST only contain information that is constant across all environments of the Python installation.

Information specific to a Python environment, such as the site-packages path, is outside the scope for this file, and the PEP authors expect that a static environment description file will be introduced via a future PEP.

Specification

Starting from Python 3.14, a file named build-details.json following the format specified in this PEP, or a future version, MUST be installed in the platform-independent standard library directory (stdlib, eg. /usr/lib/python3.14/build-details.json), UNLESS unfeasible due to technical limitations.

Attention

In addition to the standard location specified by this PEP, the build-details.json file MAY also be installed into additional locations, and under a different name. Notwithstanding, the file SHOULD still be available at the standard location.

In actuality, the PEP authors expect future PEPs to define additional install locations with 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.0.schema.json
Title build-details.json — a static description file with build details of Python installations
Type object
Additional properties Not allowed

schema_version

Type string (constant — 1.0)
Description Schema version.

This is a string following the format <MAJOR>.<MINOR>, where <MAJOR> and <MINOR> are unpadded numbers and represent the major and minor components of the version. Versions may be arithmetically compared by interpreting the version string as a decimal number.

For this specification version, this value is constant and MUST be 1.0.

Future versions of this schema MUST use a higher version number. Future versions of this schema MUST NOT use the same major version component as other schema version unless its specification is deemed backwards-compatible with them — it can’t change, or extend, any parts of the current specification in such a way as the semantics of the interpreted data differ, or that data valid under the new specification is invalid under the older specification, with the exception of additional properties (errors caused by additionalProperties).

Required True

base_prefix

Type string
Description Base prefix of the Python installation.

Either an absolute path, or a path relative to directory where this file is contained.

Examples /usr, ../.., etc.
Required True

base_interpreter

Type string
Description The path to the Python interpreter of the base installation.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the installation provides an interpreter executable.

Examples
  • /usr/bin/python
  • bin/python
  • etc.
Required False

platform

Type string
Description System platform string.

This field SHOULD be equivalent to sysconfig.get_platform().

Examples
  • linux-x86_64
  • etc.
Required True

language

Type object
Description Object containing details related to the Python language specification.
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 sysconfig.get_python_version().

Examples 3.14, etc.
Required True

language.version_info

Type object
Description Object in the format of sys.version_info.

This section SHOULD be equivalent to sys.version_info.

Examples
  • {'major': 3, 'minor': 14, 'micro': 1, 'releaselevel': 'final', 'serial': 0}
  • etc.
Required False
Additional properties Not allowed
language.version_info.major
Type number
Required True
language.version_info.minor
Type number
Required True
language.version_info.micro
Type number
Required True
language.version_info.releaselevel
Type string (enum — alpha, beta, candidate, final)
Required True
language.version_info.serial
Type number
Required True

implementation

Type object
Description Object containing details related to the Python implementation.

This section SHOULD be equivalent to sys.implementation. It follows the specification defined in PEP 421, meaning that in addition to the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore.

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
  • {'major': 3, 'minor': 14, 'micro': 1, 'releaselevel': 'final', 'serial': 0}
  • {'major': 7, 'minor': 3, 'micro': 16, 'releaselevel': 'final', 'serial': 0}
  • etc.
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

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
  • .cpython-314-x86_64-linux-gnu.so
  • etc.
Required False

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 MUST be present if the Python installation supports importing external files, and it SHOULD be equivalent to the importlib.machinery.*_SUFFIXES attributes.

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.

Examples
  • {'source': ['.py'], 'bytecode': ['.pyc'], 'optimized_bytecode': ['.pyc'], 'debug_bytecode': ['.pyc'], 'extensions': ['.cpython-313-x86_64-linux-gnu.so', '.abi3.so', '.so']}
  • etc.
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 libpython library, otherwise this section will be missing.

Required False
Additional properties Not allowed

libpython.dynamic

Type string
Description The path to the dynamic libpython library.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the Python installation provides a dynamic libpython library, otherwise this entry will be missing.

Examples
  • /usr/lib/libpython3.14.so.1.0
  • lib/libpython3.14.so.1.0
  • etc.
Required False

libpython.dynamic_stableabi

Type string
Description The path to the dynamic libpython library for the stable ABI.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the Python installation provides a dynamic libpython library targetting the Stable ABI, otherwise this entry will be missing.

If this key is present dynamic MUST also be set.

Examples
  • /usr/lib/libpython3.so
  • lib/libpython3.so
  • etc.
Required False

libpython.static

Type string
Description The path to the static libpython library.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the Python installation provides a static libpython library, otherwise this entry will be missing.

Examples
  • /usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a
  • lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a
  • etc.
Required False

c_api

Type object
Description Object containing details related to the Python C API.

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 path relative to base_prefix.

Examples
  • /usr/include/python3.14
  • include/python3.14
  • etc.
Required True

c_api.pkgconfig_path

Type string
Description The path to the pkg-config definition files.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the Python implementation provides pkg-config definition files, otherwise this section will be missing.

Examples
  • /usr/lib/pkgconfig
  • lib/pkgconfig
  • etc.
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. Implementations may choose what data to provide in this section.

Required False
Additional properties Allowed

Example

 1{
 2  "schema_version": "1.0",
 3  "base_prefix": "/usr",
 4  "base_interpreter": "/usr/bin/python",
 5  "platform": "linux-x86_64",
 6  "language": {
 7    "version": "3.14",
 8    "version_info": {
 9      "major": 3,
10      "minor": 14,
11      "micro": 0,
12      "releaselevel": "alpha",
13      "serial": 0
14    }
15  },
16  "implementation": {
17    "name": "cpython",
18    "version": {
19      "major": 3,
20      "minor": 14,
21      "micro": 0,
22      "releaselevel": "alpha",
23      "serial": 0
24    },
25    "hexversion": 51249312,
26    "cache_tag": "cpython-314",
27    "_multiarch": "x86_64-linux-gnu"
28  },
29  "abi": {
30    "flags": ["t", "d"],
31    "extension_suffix": ".cpython-314-x86_64-linux-gnu.so",
32    "stable_abi_suffix": ".abi3.so"
33  },
34  "suffixes": {
35    "source": [".py"],
36    "bytecode": [".pyc"],
37    "optimized_bytecode": [".pyc"],
38    "debug_bytecode": [".pyc"],
39    "extensions": [".cpython-314-x86_64-linux-gnu.so", ".abi3.so", ".so"]
40  },
41  "libpython": {
42    "dynamic": "/usr/lib/libpython3.14.so.1.0",
43    "dynamic_stableabi": "/usr/lib/libpython3.so",
44    "static": "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
45    "link_extensions": true
46  },
47  "c_api": {
48    "headers": "/usr/include/python3.14",
49    "pkgconfig_path": "/usr/lib/pkgconfig"
50  }
51}

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.0.schema.json",
  4  "type": "object",
  5  "title": "build-details.json — a static description file with build details of Python installations",
  6  "required": [
  7    "schema_version",
  8    "base_prefix",
  9    "platform",
 10    "language",
 11    "implementation"
 12  ],
 13  "additionalProperties": false,
 14  "properties": {
 15    "schema_version": {
 16      "type": "string",
 17      "description": "Schema version.\n\nThis is a string following the format ``<MAJOR>.<MINOR>``, where ``<MAJOR>`` and ``<MINOR>`` are unpaded numbers and represent the **major** and **minor** components of the version. Versions may be arithmetically compared by intrepreting the version string as a decimal number.\n\nFor this specification version, this value is constant and **MUST** be ``1.0``.\n\nFuture versions of this schema **MUST** use a higher version number. Future versions of this schema **MUST NOT** use the same **major** version component as other schema version unless its specification is deemed backwards-compatible with them — it can't change, or extend, any parts of the current specification in such a way as the semantics of the interpreted data differ, or that data valid under the new specification is invalid under the older specification, with the exception of additional properties (errors caused by ``additionalProperties``).",
 18      "const": "1.0"
 19    },
 20    "base_prefix": {
 21      "type": "string",
 22      "description": "Base prefix of the Python installation.\n\nEither an absolute path, or a path relative to directory where this file is contained.",
 23      "examples": [
 24        "/usr",
 25        "../.."
 26      ]
 27    },
 28    "base_interpreter": {
 29        "type": "string",
 30        "description": "The path to the Python interprer of the base installation.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the installation provides an interpreter executable.",
 31        "examples": [
 32          "/usr/bin/python",
 33          "bin/python"
 34        ]
 35    },
 36    "platform": {
 37      "type": "string",
 38      "description": "System platform string.\n\nThis field **SHOULD** be equivalent to ``sysconfig.get_platform()``.",
 39      "examples": [
 40        "linux-x86_64"
 41      ]
 42    },
 43    "language": {
 44      "type": "object",
 45      "description": "Object containing details related to the Python language specification.",
 46      "required": [
 47        "version"
 48      ],
 49      "additionalProperties": false,
 50      "properties": {
 51        "version": {
 52          "type": "string",
 53          "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()``.",
 54          "examples": ["3.14"]
 55        },
 56        "version_info": {
 57          "type": "object",
 58          "description": "Object in the format of :py:data:`sys.version_info`.\n\nThis section **SHOULD** be equivalent to :py:data:`sys.version_info`.",
 59          "required": ["major", "minor", "micro", "releaselevel", "serial"],
 60          "additionalProperties": false,
 61          "examples": [
 62            {
 63              "major": 3,
 64              "minor": 14,
 65              "micro": 1,
 66              "releaselevel": "final",
 67              "serial": 0
 68            }
 69          ],
 70          "properties": {
 71            "major": {
 72              "type": "number"
 73            },
 74            "minor": {
 75              "type": "number"
 76            },
 77            "micro": {
 78              "type": "number"
 79            },
 80            "releaselevel": {
 81              "type": "string",
 82              "enum": ["alpha", "beta", "candidate", "final"]
 83            },
 84            "serial": {
 85              "type": "number"
 86            }
 87          }
 88        }
 89      }
 90    },
 91    "implementation": {
 92      "type": "object",
 93      "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.",
 94      "required": [
 95        "name",
 96        "version",
 97        "hexversion",
 98        "cache_tag"
 99      ],
100      "additionalProperties": true,
101      "properties": {
102        "name": {
103          "type": "string",
104          "description": "Lower-case name of the Python implementation.",
105          "examples": ["cpython", "pypy"]
106        },
107        "version": {
108          "type": "object",
109          "description": "Object in the format of :py:data:`sys.version_info`, containing the implementation version.",
110          "required": ["major", "minor", "micro", "releaselevel", "serial"],
111          "additionalProperties": false,
112          "examples": [
113            {
114              "major": 3,
115              "minor": 14,
116              "micro": 1,
117              "releaselevel": "final",
118              "serial": 0
119            },
120            {
121              "major": 7,
122              "minor": 3,
123              "micro": 16,
124              "releaselevel": "final",
125              "serial": 0
126            }
127          ],
128          "properties": {
129            "major": {
130              "type": "number"
131            },
132            "minor": {
133              "type": "number"
134            },
135            "micro": {
136              "type": "number"
137            },
138            "releaselevel": {
139              "type": "string",
140              "enum": ["alpha", "beta", "candidate", "final"]
141            },
142            "serial": {
143              "type": "number"
144            }
145          }
146        }
147      }
148    },
149    "abi": {
150      "type": "object",
151      "description": "Object containing details related to ABI.",
152      "required": [
153        "flags"
154      ],
155      "additionalProperties": false,
156      "properties": {
157        "flags": {
158          "type": "array",
159          "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.",
160          "additionalProperties": true,
161          "examples": [
162            ["t", "d"]
163          ]
164        },
165        "extension_suffix": {
166          "type": "string",
167          "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.",
168          "examples": [
169            ".cpython-314-x86_64-linux-gnu.so"
170          ]
171        },
172        "stable_abi_suffix": {
173          "type": "string",
174          "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.",
175          "examples": [
176            ".abi3.so"
177          ]
178        }
179      }
180    },
181    "suffixes": {
182      "type": "object",
183      "description": "Valid module suffixes grouped by type.\n\nThis section **MUST** be present if the Python installation supports importing external files, and it **SHOULD** be equivalent to the ``importlib.machinery.*_SUFFIXES`` attributes.\n\nAdditionally, if a Python implementation provides extension kinds other than the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-section for them.",
184      "examples": [
185        {
186          "source": [".py"],
187          "bytecode": [".pyc"],
188          "optimized_bytecode": [".pyc"],
189          "debug_bytecode": [".pyc"],
190          "extensions": [".cpython-313-x86_64-linux-gnu.so", ".abi3.so", ".so"]
191        }
192      ]
193    },
194    "libpython": {
195      "type": "object",
196      "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.",
197      "additionalProperties": false,
198      "properties": {
199        "dynamic": {
200          "type": "string",
201          "description": "The path to the dynamic ``libpython`` library.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing.",
202          "examples": [
203            "/usr/lib/libpython3.14.so.1.0",
204            "lib/libpython3.14.so.1.0"
205          ]
206        },
207        "dynamic_stableabi": {
208          "type": "string",
209          "description": "The path to the dynamic ``libpython`` library for the stable ABI.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library targetting the Stable ABI, otherwise this entry will be missing.\n\nIf this key is present ``dynamic`` **MUST** also be set.",
210          "examples": [
211            "/usr/lib/libpython3.so",
212            "lib/libpython3.so"
213          ]
214        },
215        "static": {
216          "type": "string",
217          "description": "The path to the static ``libpython`` library.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a static ``libpython`` library, otherwise this entry will be missing.",
218          "examples": [
219            "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
220            "lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a"
221          ]
222        },
223        "link_extensions": {
224          "type": "boolean",
225          "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."
226        }
227      }
228    },
229    "c_api": {
230      "type": "object",
231      "description": "Object containing details related to the Python C API.\n\nThis section **MUST** be present if the Python implementation provides a C API, otherwise this section will be missing.",
232      "required": [
233        "headers"
234      ],
235      "additionalProperties": false,
236      "properties": {
237        "headers": {
238          "type": "string",
239          "description": "The path to the C API headers.\n\nEither an absolute path, or a path relative to ``base_prefix``.",
240          "examples": [
241            "/usr/include/python3.14",
242            "include/python3.14"
243          ]
244        },
245        "pkgconfig_path": {
246          "type": "string",
247          "description": "The path to the pkg-config definition files.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python implementation provides pkg-config definition files, otherwise this section will be missing.",
248          "examples": [
249            "/usr/lib/pkgconfig",
250            "lib/pkgconfig"
251          ]
252        }
253      }
254    },
255    "arbitrary_data": {
256      "type": "object",
257      "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. Implementations may choose what data to provide in this section.",
258      "additionalProperties": true
259    }
260  }
261}

Rejected Ideas

Including environment-specific data

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.

Including environment-specific data in the config file means that it would be environment-specific, so virtual environments would need their own config file. This is problematic because virtual environments survive updates of the base Python installation, creating the possibily for the static config file to be outdated, and making its data unreliable, which defeats its purpose.

The proposed solution, partially implemented in this PEP, is to have a build-details.json file, referent to the base Python installation, and a environment.json file, referent to the specific environment.

With build-details.json being part of the Python distribution, when the base Python installation gets updated, build-details.json does too, ensuring the static description files are never outdated.


Source: https://github.com/python/peps/blob/main/peps/pep-0739.rst

Last modified: 2025-02-07 01:10:57 GMT