iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
python-peps/peps/pep-0739.rst

566 lines
12 KiB
ReStructuredText
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink