diff --git a/peps/pep-0739.rst b/peps/pep-0739.rst new file mode 100644 index 000000000..67871b70b --- /dev/null +++ b/peps/pep-0739.rst @@ -0,0 +1,140 @@ +PEP: 739 +Title: Static description file for Python installations +Author: Filipe LaĆ­ns +PEP-Delegate: Paul Moore +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.