python-peps/peps/pep-0739.rst

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

..
    Rendered with https://gist.github.com/FFY00/eb02d9da2870aae547bc579b7e17a145

.. _spec-start:

.. list-table::
    :widths: 25 75

    * - ``$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``
------------------

.. list-table::
    :widths: 25 75

    * - 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``
---------------

.. list-table::
    :widths: 25 75

    * - 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``
------------

.. list-table::
    :widths: 25 75

    * - Type
      - ``string``
    * - Description
      - System platform string.
    * - Examples
      - - ``linux-x86_64``
        - etc.
    * - Required
      - **True**

``language``
------------

.. list-table::
    :widths: 25 75

    * - 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``
~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - 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``
------------------

.. list-table::
    :widths: 25 75

    * - Type
      - ``object``
    * - Description
      - Object containing details related to Python implementation.

        This section SHOULD be equivalent to
        :py:data:`sys.implementation`, but only the ``name`` and
        ``version`` keys are actually required to be present.
    * - Required
      - **True**
    * - Additional properties
      - **Allowed**

``implementation.name``
~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - Type
      - ``string``
    * - Description
      - Lower-case name of the Python implementation.
    * - Examples
      - ``cpython``, ``pypy``, etc.
    * - Required
      - **True**

``implementation.version``
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - Type
      - ``object``
    * - Description
      - Object in the format of :py:data:`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``
++++++++++++++++++++++++++++++++

.. list-table::
    :widths: 25 75

    * - Type
      - ``number``
    * - Required
      - **True**

``implementation.version.minor``
++++++++++++++++++++++++++++++++

.. list-table::
    :widths: 25 75

    * - Type
      - ``number``
    * - Required
      - **True**

``implementation.version.micro``
++++++++++++++++++++++++++++++++

.. list-table::
    :widths: 25 75

    * - Type
      - ``number``
    * - Required
      - **True**

``implementation.version.releaselevel``
+++++++++++++++++++++++++++++++++++++++

.. list-table::
    :widths: 25 75

    * - Type
      - ``string`` (enum — ``alpha``, ``beta``, ``candidate``, ``final``)
    * - Required
      - **True**

``implementation.version.serial``
+++++++++++++++++++++++++++++++++

.. list-table::
    :widths: 25 75

    * - Type
      - ``number``
    * - Required
      - **True**

``interpreter``
---------------

.. list-table::
    :widths: 25 75

    * - 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``
~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - 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``
-------

.. list-table::
    :widths: 25 75

    * - Type
      - ``object``
    * - Description
      - Object containing details related to ABI.
    * - Required
      - **False**
    * - Additional properties
      - **Not allowed**

``abi.flags``
~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - 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``
~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - 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``
~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

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

``suffixes``
------------

.. list-table::
    :widths: 25 75

    * - 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``
-------------

.. list-table::
    :widths: 25 75

    * - 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``
~~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - 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``
~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - 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**

``libpython.link_to_libpython``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - Type
      - ``boolean``
    * - Description
      - Should extensions built against a dynamic ``libpython`` link to
        it?
    * - Required
      - **False**

``c_api``
---------

.. list-table::
    :widths: 25 75

    * - 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``
~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - 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``
~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
    :widths: 25 75

    * - 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``
------------------

.. list-table::
    :widths: 25 75

    * - 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**


.. _spec-end:


Example
=======


.. literalinclude:: pep-0739/example.json
   :language: json
   :linenos:


JSON Schema
===========

.. literalinclude:: pep-0739/python-build-info-v1.schema.json
   :language: json
   :linenos:


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 across 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.