201 lines
5.4 KiB
ReStructuredText
201 lines
5.4 KiB
ReStructuredText
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.
|