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 :py:data:`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 :py:data:`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
=======


.. code-block:: json

   {
     "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.