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 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 dynamic libpython 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 static libpython 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.

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

Last modified: 2024-03-13 13:01:38 GMT