python-peps/peps/pep-0739.rst

PEP: 739
Title: Static description file for Python installations
Author: Filipe Laíns <lains@riseup.net>
PEP-Delegate: Paul Moore <p.f.moore@gmail.com>
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 to describe Python
installations.


Rationale
=========

When introspecting a Python installation, running code is often undesirable or
impossible. Having a static description file makes various of Python
installation 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 standard format for a file describing Python
installations, distributing such files is out of scope.

Python implementations may choose to include a self-describing file as part of
their distribution, but they are not required to, and it is out of scope for
this PEP to define how that may happen, if they decide to do so.


Specification
=============

The standard Python installation 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.

language
--------

Subsection with details related to the language specification.

version
~~~~~~~

:Type: ``string``
:Description: String representation the Python language version. Same as the
              ``PY_VERSION`` macro on CPython.

version_parts
~~~~~~~~~~~~~

:Type: ``object``
:Description: Equivalent to :py:data:`sys.version_info`.

implementation
--------------

Subsection with details related to Python implementation. While only the
``name`` key is required in this section, this section SHOULD be equivalent to
:py:data:`sys.implementation` on most implementations.

name
~~~~

:Type: ``string``
:Description: Lower-case name of the Python implementation.

Implementation-specific keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Additionally to the keys defined above, implementations may choose to include
extra keys with extra implementation-specific details.

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.

TODO

libpython
---------

Subsection with details related to the ``libpython``, if available. If the
Python implementation does not provide a ``libpython`` library, this section
will be missing.

TODO

Example
=======


.. code-block:: json

   {
     "schema_version": 1,
     "language": {
       "version": "3.13.1",
       "version_parts": {
         "major": 3,
         "minor": 13,
         "micro": 1,
         "releaselevel": "final",
         "serial": 0
       }
     },
     "implementation": {
       "name": "cpython",
       "hexversion": "...",
       "cache_tag": "cpython-313",
       "multiarch": "x86_64-linux-gnu"
     },
     "c_api": {
     }
   }

Copyright
=========

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