PEP 739: Static description file for Python installations (#3599)

peps/pep-0739.rst

@@ -0,0 +1,140 @@
+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.