Skip to content

Latest commit

 

History

History
200 lines (146 loc) · 5.43 KB

pep-0739.rst

File metadata and controls

200 lines (146 loc) · 5.43 KB
Raw

PEP: 739 Title: Static description file for build details of Python installations Author: Filipe Laíns <lains@riseup.net> PEP-Delegate: Paul Moore <p.f.moore@gmail.com> Discussions-To: https://discuss.python.org/t/pep-739-static-description-file-for-build-details-of-python-installations/44572 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 :pysys.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 :pysys.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.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.