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

Python Enhancement Proposals

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
Table of Contents

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 may happen are out of scope for this PEP.

Specification

The 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 1. Future iterations of this schema MUST update this value.
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.
Examples
  • linux-x86_64
  • etc.
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.
Examples 3.13, etc.
Required True

implementation

Type object
Description Object containing details related to Python implementation.

This section SHOULD be equivalent to sys.implementation, but only the name and version keys are actually required to be present.
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': 13, '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

interpreter

Type object
Description Object containing details Python interpreter.

If the Python installation does not provide an interpreter, 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 key.
Examples
  • /usr/bin/python
  • bin/python
  • etc.
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 ['d', 't'], etc.
Required True

abi.extension_suffix

Type string
Description Suffix used for extensions built against the current implementation version.
Examples
  • .cpython-313-x86_64-linux-gnu.so
  • etc.
Required True

abi.stable_abi_suffix

Type string
Description Suffix used for extensions built against the stable ABI.
Examples .abi3.so, etc.
Required False

suffixes

Type object
Description Valid module suffixes grouped by type.
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.

If the Python installation does not provide a libpython library, 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 relative path to the path defined in the base key.. If the Python installation does not provide a dynamic libpython library, this entry will be missing.
Examples
  • /usr/lib/libpython3.13.so.1.0
  • lib/libpython3.13.so.1.0
  • etc.
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 key.. If the Python installation does not provide a static libpython library, this entry will be missing.
Examples
  • /usr/lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a
  • lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a
  • etc.
Required False

c_api

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

If the Python implementation does not provide a C API, 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 key..
Examples
  • /usr/include/python3.13
  • include/python3.13
  • etc.
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 key..
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.
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.13"
 7  },
 8  "implementation": {
 9    "name": "cpython",
10    "version": {
11      "major": 3,
12      "minor": 13,
13      "micro": 1,
14      "releaselevel": "final",
15      "serial": 0
16    },
17    "hexversion": 51184112,
18    "cache_tag": "cpython-313",
19    "_multiarch": "x86_64-linux-gnu"
20  },
21  "interpreter": {
22    "path": "/usr/bin/python"
23  },
24  "abi": {
25    "flags": ["d", "t"],
26    "extension_suffix": ".cpython-313-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-313-x86_64-linux-gnu.so", ".abi3.so", ".so"]
35  },
36  "libpython": {
37    "dynamic": "/usr/lib/libpython3.13.so.1.0",
38    "static": "/usr/lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a",
39    "link_to_libpython": true
40  },
41  "c_api": {
42    "headers": "/usr/include/python3.13",
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. This is a constant value and MUST be ``1``. 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.",
 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.",
 45          "examples": ["3.13"]
 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`, but only the ``name`` and ``version`` keys are actually required to be present.",
 52      "required": [
 53        "name",
 54        "version"
 55      ],
 56      "additionalProperties": true,
 57      "properties": {
 58        "name": {
 59          "type": "string",
 60          "description": "Lower-case name of the Python implementation.",
 61          "examples": ["cpython", "pypy"]
 62        },
 63        "version": {
 64          "type": "object",
 65          "description": "Object in the format of :py:data:`sys.version_info`, containing the implementation version.",
 66          "required": ["major", "minor", "micro", "releaselevel", "serial"],
 67          "additionalProperties": false,
 68          "examples": [
 69            {
 70              "major": 3,
 71              "minor": 13,
 72              "micro": 1,
 73              "releaselevel": "final",
 74              "serial": 0
 75            },
 76            {
 77              "major": 7,
 78              "minor": 3,
 79              "micro": 16,
 80              "releaselevel": "final",
 81              "serial": 0
 82            }
 83          ],
 84          "properties": {
 85            "major": {
 86              "type": "number"
 87            },
 88            "minor": {
 89              "type": "number"
 90            },
 91            "micro": {
 92              "type": "number"
 93            },
 94            "releaselevel": {
 95              "type": "string",
 96              "enum": ["alpha", "beta", "candidate", "final"]
 97            },
 98            "serial": {
 99              "type": "number"
100            }
101          }
102        }
103      }
104    },
105    "interpreter": {
106      "type": "object",
107      "description": "Object containing details Python interpreter.\n\nIf the Python installation does not provide an interpreter, this section will be missing.",
108      "required": [
109        "path"
110      ],
111      "additionalProperties": false,
112      "properties": {
113        "path": {
114          "type": "string",
115          "description": "The path to the Python interprer. Either an absolute path, or a relative path to the path defined in the ``base`` key.",
116          "examples": [
117            "/usr/bin/python",
118            "bin/python"
119          ]
120        }
121      }
122    },
123    "abi": {
124      "type": "object",
125      "description": "Object containing details related to ABI.",
126      "required": [
127        "flags",
128        "extension_suffix"
129      ],
130      "additionalProperties": false,
131      "properties": {
132        "flags": {
133          "type": "array",
134          "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.",
135          "additionalProperties": true,
136          "examples": [
137            ["d", "t"]
138          ]
139        },
140        "extension_suffix": {
141          "type": "string",
142          "description": "Suffix used for extensions built against the current implementation version.",
143          "examples": [
144            ".cpython-313-x86_64-linux-gnu.so"
145          ]
146        },
147        "stable_abi_suffix": {
148          "type": "string",
149          "description": "Suffix used for extensions built against the stable ABI.",
150          "examples": [
151            ".abi3.so"
152          ]
153        }
154      }
155    },
156    "suffixes": {
157      "type": "object",
158      "description": "Valid module suffixes grouped by type.",
159      "examples": [
160        {
161          "source": [".py"],
162          "bytecode": [".pyc"],
163          "optimized_bytecode": [".pyc"],
164          "debug_bytecode": [".pyc"],
165          "extensions": [".cpython-313-x86_64-linux-gnu.so", ".abi3.so", ".so"]
166        }
167      ]
168    },
169    "libpython": {
170      "type": "object",
171      "description": "Object containing details related to the ``libpython`` library.\n\nIf the Python installation does not provide a ``libpython`` library, this section will be missing.",
172      "additionalProperties": false,
173      "properties": {
174        "dynamic": {
175          "type": "string",
176          "description": "The path to the dynamic ``libpython`` library.\n\nEither an absolute path, or a relative path to the path defined in the ``base`` key.. If the Python installation does not provide a dynamic ``libpython`` library, this entry will be missing.",
177          "examples": [
178            "/usr/lib/libpython3.13.so.1.0",
179            "lib/libpython3.13.so.1.0"
180          ]
181        },
182        "static": {
183          "type": "string",
184          "description": "The path to the static ``libpython`` library.\n\nEither an absolute path, or a relative path to the path defined in the ``base`` key.. If the Python installation does not provide a static ``libpython`` library, this entry will be missing.",
185          "examples": [
186            "/usr/lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a",
187            "lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a"
188          ]
189        },
190        "link_to_libpython": {
191          "type": "boolean",
192          "description": "Should extensions built against a dynamic ``libpython`` link to it?"
193        }
194      }
195    },
196    "c_api": {
197      "type": "object",
198      "description": "Object containing details related to the Python C API, if available.\n\nIf the Python implementation does not provide a C API, this section will be missing.",
199      "required": [
200        "headers"
201      ],
202      "additionalProperties": false,
203      "properties": {
204        "headers": {
205          "type": "string",
206          "description": "The path to the C API headers. Either an absolute path, or a relative path to the path defined in the ``base`` key..",
207          "examples": [
208            "/usr/include/python3.13",
209            "include/python3.13"
210          ]
211        },
212        "pkgconfig_path": {
213          "type": "string",
214          "description": "The path to the pkg-config definition files. Either an absolute path, or a relative path to the path defined in the ``base`` key..",
215          "examples": [
216            "/usr/lib/pkgconfig",
217            "lib/pkgconfig"
218          ]
219        }
220      }
221    },
222    "arbitrary_data": {
223      "type": "object",
224      "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.",
225      "additionalProperties": true
226    }
227  }
228}

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.

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

Last modified: 2024-06-26 06:54:06 GMT