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

PEP 739: Update based on discussion feedback (#3954)

This commit is contained in:
Filipe Laíns 🇵🇸 2024-09-12 03:43:59 +01:00 committed by GitHub
parent ce38a96f43
commit 430987f98a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 141 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
peps/pep-0739.rst
View File

@ -7,7 +7,7 @@ Status: Draft
Type: Standards Track Type: Standards Track
Topic: Packaging Topic: Packaging
Created: 19-Dec-2023 Created: 19-Dec-2023
Python-Version: 3.13 Python-Version: 3.14
Abstract Abstract
@ -30,16 +30,38 @@ This is helpful for use-cases such as cross-compilation, Python launchers, etc.
Scope Scope
===== =====
This PEP only defines a format. Python implementations may choose to include a This PEP defines a format for the description file, and a standard location for
build details file as part of their distribution, but they are not required to, where to place it.
and the specifics of how that may happen are out of scope for this PEP.
Specification Location
============= ========
The specification is defined by the JSON Schema definition provided below, which When possible, Python installations should install the static description file
is rendered in an human-readable format here. inside the standard library directory, with the name ``build-details.json``
(Eg. ``/usr/lib/python3.14/build-details.json``).
.. important::
Given that there may be technical challenges, Python implementations are not
required to provide the file if not feasable. In such scenarios, they may
choose to provide it in a different maner.
.. attention::
Notwithstanding the standard location specified here, it does not prevent the
file from **additionally** being provided in another location, and with a
different name. In fact, the PEP authors expect future PEPs to define
additional locations to install this file, for better discoverability.
Format
======
The format 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 Rendered with https://gist.github.com/FFY00/eb02d9da2870aae547bc579b7e17a145
@ -70,8 +92,11 @@ is rendered in an human-readable format here.
* - Type * - Type
- ``string`` (constant — ``1``) - ``string`` (constant — ``1``)
* - Description * - Description
- Schema version. This is a constant value and MUST be ``1``. - Schema version.
Future iterations of this schema MUST update this value.
This is a constant value and MUST be ``1``, when using the
schema described here. Future iterations of this schema MUST
update this value.
* - Required * - Required
- **True** - **True**
@ -103,6 +128,8 @@ is rendered in an human-readable format here.
- ``string`` - ``string``
* - Description * - Description
- System platform string. - System platform string.
This field SHOULD be equivalent to ``sysconfig.get_platform()``.
* - Examples * - Examples
- - ``linux-x86_64`` - - ``linux-x86_64``
- etc. - etc.
@ -139,8 +166,11 @@ is rendered in an human-readable format here.
* - Description * - Description
- String representation the Python language version — a version - String representation the Python language version — a version
string consisting only of the *major* and *minor* components. string consisting only of the *major* and *minor* components.
This field SHOULD be equivalent to
``sysconfig.get_python_version()``.
* - Examples * - Examples
- ``3.13``, etc. - ``3.14``, etc.
* - Required * - Required
- **True** - **True**
@ -156,8 +186,10 @@ is rendered in an human-readable format here.
- Object containing details related to Python implementation. - Object containing details related to Python implementation.
This section SHOULD be equivalent to This section SHOULD be equivalent to
:py:data:`sys.implementation`, but only the ``name`` and :py:data:`sys.implementation`. It follows specification defined
``version`` keys are actually required to be present. in PEP 421, meaning that on top of the required keys,
implementation-specific keys can also exist, but must be
prefixed with an underscore.
* - Required * - Required
- **True** - **True**
* - Additional properties * - Additional properties
@ -264,8 +296,8 @@ is rendered in an human-readable format here.
* - Description * - Description
- Object containing details Python interpreter. - Object containing details Python interpreter.
If the Python installation does not provide an interpreter, this This section MUST be present if the Python installation provides
section will be missing. an interpreter binary, otherwise this section will be missing.
* - Required * - Required
- **False** - **False**
* - Additional properties * - Additional properties
@ -281,7 +313,7 @@ is rendered in an human-readable format here.
- ``string`` - ``string``
* - Description * - Description
- The path to the Python interprer. Either an absolute path, or a - The path to the Python interprer. Either an absolute path, or a
relative path to the path defined in the ``base`` key. relative path to the path defined in the ``base_prefix`` key.
* - Examples * - Examples
- - ``/usr/bin/python`` - - ``/usr/bin/python``
- ``bin/python`` - ``bin/python``
@ -319,7 +351,7 @@ is rendered in an human-readable format here.
The flags MUST be defined in the order they appear on the The flags MUST be defined in the order they appear on the
extension suffix. extension suffix.
* - Examples * - Examples
- ``['d', 't']``, etc. - ``['t', 'd']``, etc.
* - Required * - Required
- **True** - **True**
@ -334,8 +366,11 @@ is rendered in an human-readable format here.
* - Description * - Description
- Suffix used for extensions built against the current - Suffix used for extensions built against the current
implementation version. implementation version.
This field MUST be present if the Python implementation supports
extensions, otherwise this entry will be missing.
* - Examples * - Examples
- - ``.cpython-313-x86_64-linux-gnu.so`` - - ``.cpython-314-x86_64-linux-gnu.so``
- etc. - etc.
* - Required * - Required
- **True** - **True**
@ -350,6 +385,10 @@ is rendered in an human-readable format here.
- ``string`` - ``string``
* - Description * - Description
- Suffix used for extensions built against the stable ABI. - Suffix used for extensions built against the stable ABI.
This field MUST be present if the Python implementation has a
stable ABI extension suffix, otherwise this entry will be
missing.
* - Examples * - Examples
- ``.abi3.so``, etc. - ``.abi3.so``, etc.
* - Required * - Required
@ -365,6 +404,16 @@ is rendered in an human-readable format here.
- ``object`` - ``object``
* - Description * - Description
- Valid module suffixes grouped by type. - Valid module suffixes grouped by type.
This section SHOULD be equivalent to the
``importlib.machinery.*_SUFFIXES`` attributes, if the
implementation provides such suffixes. However, if the Python
implementation does not provide suffixes of the kind specified
by any of the attributes, the equivalent sub-section is not
required to be present. Additionally, if a Python implementation
provides extension kinds other than the ones listed on
``importlib.machinery`` module, they MAY add a sub-section for
them.
* - Examples * - Examples
- - ``{'source': ['.py'], 'bytecode': ['.pyc'], 'optimized_bytecode': ['.pyc'], 'debug_bytecode': ['.pyc'], 'extensions': ['.cpython-313-x86_64-linux-gnu.so', '.abi3.so', '.so']}`` - - ``{'source': ['.py'], 'bytecode': ['.pyc'], 'optimized_bytecode': ['.pyc'], 'debug_bytecode': ['.pyc'], 'extensions': ['.cpython-313-x86_64-linux-gnu.so', '.abi3.so', '.so']}``
- etc. - etc.
@ -384,8 +433,8 @@ is rendered in an human-readable format here.
* - Description * - Description
- Object containing details related to the ``libpython`` library. - Object containing details related to the ``libpython`` library.
If the Python installation does not provide a ``libpython`` This section MUST by present if Python installation provides a
library, this section will be missing. ``libpython`` library, otherwise this section will be missing.
* - Required * - Required
- **False** - **False**
* - Additional properties * - Additional properties
@ -400,15 +449,16 @@ is rendered in an human-readable format here.
* - Type * - Type
- ``string`` - ``string``
* - Description * - Description
- The path to the dynamic ``libpython`` library. - The path to the dynamic ``libpython`` library. Either an
absolute path, or a relative path to the path defined in the
``base_prefix`` key.
Either an absolute path, or a relative path to the path defined This field MUST be present if the Python installation provides a
in the ``base`` key.. If the Python installation does not dynamic ``libpython`` library, otherwise this entry will be
provide a dynamic ``libpython`` library, this entry will be
missing. missing.
* - Examples * - Examples
- - ``/usr/lib/libpython3.13.so.1.0`` - - ``/usr/lib/libpython3.14.so.1.0``
- ``lib/libpython3.13.so.1.0`` - ``lib/libpython3.14.so.1.0``
- etc. - etc.
* - Required * - Required
- **False** - **False**
@ -422,15 +472,16 @@ is rendered in an human-readable format here.
* - Type * - Type
- ``string`` - ``string``
* - Description * - Description
- The path to the static ``libpython`` library. - The path to the static ``libpython`` library. Either an absolute
path, or a relative path to the path defined in the
``base_prefix`` key.
Either an absolute path, or a relative path to the path defined This field MUST be present if the Python installation provides a
in the ``base`` key.. If the Python installation does not static ``libpython`` library, otherwise this entry will be
provide a static ``libpython`` library, this entry will be
missing. missing.
* - Examples * - Examples
- - ``/usr/lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a`` - - ``/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a``
- ``lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a`` - ``lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a``
- etc. - etc.
* - Required * - Required
- **False** - **False**
@ -446,6 +497,10 @@ is rendered in an human-readable format here.
* - Description * - Description
- Should extensions built against a dynamic ``libpython`` link to - Should extensions built against a dynamic ``libpython`` link to
it? it?
This field MUST be present if the Python installation provides a
dynamic ``libpython`` library, otherwise this entry will be
missing.
* - Required * - Required
- **False** - **False**
@ -461,8 +516,8 @@ is rendered in an human-readable format here.
- Object containing details related to the Python C API, if - Object containing details related to the Python C API, if
available. available.
If the Python implementation does not provide a C API, this This section MUST be present if the Python implementation
section will be missing. provides a C API, otherwise this section will be missing.
* - Required * - Required
- **False** - **False**
* - Additional properties * - Additional properties
@ -478,10 +533,10 @@ is rendered in an human-readable format here.
- ``string`` - ``string``
* - Description * - Description
- The path to the C API headers. Either an absolute path, or a - The path to the C API headers. Either an absolute path, or a
relative path to the path defined in the ``base`` key.. relative path to the path defined in the ``base_prefix`` key.
* - Examples * - Examples
- - ``/usr/include/python3.13`` - - ``/usr/include/python3.14``
- ``include/python3.13`` - ``include/python3.14``
- etc. - etc.
* - Required * - Required
- **True** - **True**
@ -496,8 +551,12 @@ is rendered in an human-readable format here.
- ``string`` - ``string``
* - Description * - Description
- The path to the pkg-config definition files. Either an absolute - The path to the pkg-config definition files. Either an absolute
path, or a relative path to the path defined in the ``base`` path, or a relative path to the path defined in the
key.. ``base_prefix`` key.
This field MUST be present if the Python implementation provides
pkg-config definition files for the C API, otherwise this
section will be missing.
* - Examples * - Examples
- - ``/usr/lib/pkgconfig`` - - ``/usr/lib/pkgconfig``
- ``lib/pkgconfig`` - ``lib/pkgconfig``
@ -518,6 +577,7 @@ is rendered in an human-readable format here.
This is meant to be used as an escape-hatch, to include any This is meant to be used as an escape-hatch, to include any
relevant data that is not covered by this specification. relevant data that is not covered by this specification.
Implamentations may choose what data to provide in this section.
* - Required * - Required
- **False** - **False**
* - Additional properties * - Additional properties
@ -552,7 +612,7 @@ Having a larger scope
One of the main requests in the discussion of this PEP was the inclusion of 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 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 of the PEP authors that information regarding the Python environment should be
provided by a separate file, creating the a clear separation between the build provided by a separate file, creating the a clear separation between the build
details, which should be immutable across any interpreter instance, and details details, which should be immutable across any interpreter instance, and details
that can change, such as environment details. that can change, such as environment details.

24
peps/pep-0739/example.json
View File

@ -3,27 +3,27 @@
"base_prefix": "/usr", "base_prefix": "/usr",
"platform": "linux-x86_64", "platform": "linux-x86_64",
"language": { "language": {
"version": "3.13" "version": "3.14"
}, },
"implementation": { "implementation": {
"name": "cpython", "name": "cpython",
"version": { "version": {
"major": 3, "major": 3,
"minor": 13, "minor": 14,
"micro": 1, "micro": 0,
"releaselevel": "final", "releaselevel": "alpha",
"serial": 0 "serial": 0
}, },
"hexversion": 51184112, "hexversion": 51249312,
"cache_tag": "cpython-313", "cache_tag": "cpython-314",
"_multiarch": "x86_64-linux-gnu" "_multiarch": "x86_64-linux-gnu"
}, },
"interpreter": { "interpreter": {
"path": "/usr/bin/python" "path": "/usr/bin/python"
}, },
"abi": { "abi": {
"flags": ["d", "t"], "flags": ["t", "d"],
"extension_suffix": ".cpython-313-x86_64-linux-gnu.so", "extension_suffix": ".cpython-314-x86_64-linux-gnu.so",
"stable_abi_suffix": ".abi3.so" "stable_abi_suffix": ".abi3.so"
}, },
"suffixes": { "suffixes": {
@ -31,15 +31,15 @@
"bytecode": [".pyc"], "bytecode": [".pyc"],
"optimized_bytecode": [".pyc"], "optimized_bytecode": [".pyc"],
"debug_bytecode": [".pyc"], "debug_bytecode": [".pyc"],
"extensions": [".cpython-313-x86_64-linux-gnu.so", ".abi3.so", ".so"] "extensions": [".cpython-314-x86_64-linux-gnu.so", ".abi3.so", ".so"]
}, },
"libpython": { "libpython": {
"dynamic": "/usr/lib/libpython3.13.so.1.0", "dynamic": "/usr/lib/libpython3.14.so.1.0",
"static": "/usr/lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a", "static": "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
"link_to_libpython": true "link_to_libpython": true
}, },
"c_api": { "c_api": {
"headers": "/usr/include/python3.13", "headers": "/usr/include/python3.14",
"pkgconfig_path": "/usr/lib/pkgconfig" "pkgconfig_path": "/usr/lib/pkgconfig"
} }
} }

56
peps/pep-0739/python-build-info-v1.schema.json
View File

@ -13,7 +13,7 @@
"properties": { "properties": {
"schema_version": { "schema_version": {
"type": "string", "type": "string",
"description": "Schema version. This is a constant value and MUST be ``1``. Future iterations of this schema MUST update this value.", "description": "Schema version.\n\nThis is a constant value and MUST be ``1``, when using the schema described here. Future iterations of this schema MUST update this value.",
"const": "1" "const": "1"
}, },
"base_prefix": { "base_prefix": {
@ -26,7 +26,7 @@
}, },
"platform": { "platform": {
"type": "string", "type": "string",
"description": "System platform string.", "description": "System platform string.\n\nThis field SHOULD be equivalent to ``sysconfig.get_platform()``.",
"examples": [ "examples": [
"linux-x86_64" "linux-x86_64"
] ]
@ -41,17 +41,19 @@
"properties": { "properties": {
"version": { "version": {
"type": "string", "type": "string",
"description": "String representation the Python language version — a version string consisting only of the *major* and *minor* components.", "description": "String representation the Python language version — a version string consisting only of the *major* and *minor* components.\n\nThis field SHOULD be equivalent to ``sysconfig.get_python_version()``.",
"examples": ["3.13"] "examples": ["3.14"]
} }
} }
}, },
"implementation": { "implementation": {
"type": "object", "type": "object",
"description": "Object containing details related to Python implementation.\n\nThis section SHOULD be equivalent to :py:data:`sys.implementation`, but only the ``name`` and ``version`` keys are actually required to be present.", "description": "Object containing details related to Python implementation.\n\nThis section SHOULD be equivalent to :py:data:`sys.implementation`. It follows specification defined in PEP 421, meaning that on top of the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore.",
"required": [ "required": [
"name", "name",
"version" "version",
"hexversion",
"cache_tag"
], ],
"additionalProperties": true, "additionalProperties": true,
"properties": { "properties": {
@ -104,7 +106,7 @@
}, },
"interpreter": { "interpreter": {
"type": "object", "type": "object",
"description": "Object containing details Python interpreter.\n\nIf the Python installation does not provide an interpreter, this section will be missing.", "description": "Object containing details Python interpreter.\n\nThis section MUST be present if the Python installation provides an interpreter binary, otherwise this section will be missing.",
"required": [ "required": [
"path" "path"
], ],
@ -112,7 +114,7 @@
"properties": { "properties": {
"path": { "path": {
"type": "string", "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.", "description": "The path to the Python interprer. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.",
"examples": [ "examples": [
"/usr/bin/python", "/usr/bin/python",
"bin/python" "bin/python"
@ -134,19 +136,19 @@
"description": "Build configuration flags, used to calculate the extension suffix.\n\nThe flags MUST be defined in the order they appear on the extension suffix.", "description": "Build configuration flags, used to calculate the extension suffix.\n\nThe flags MUST be defined in the order they appear on the extension suffix.",
"additionalProperties": true, "additionalProperties": true,
"examples": [ "examples": [
["d", "t"] ["t", "d"]
] ]
}, },
"extension_suffix": { "extension_suffix": {
"type": "string", "type": "string",
"description": "Suffix used for extensions built against the current implementation version.", "description": "Suffix used for extensions built against the current implementation version.\n\nThis field MUST be present if the Python implementation supports extensions, otherwise this entry will be missing.",
"examples": [ "examples": [
".cpython-313-x86_64-linux-gnu.so" ".cpython-314-x86_64-linux-gnu.so"
] ]
}, },
"stable_abi_suffix": { "stable_abi_suffix": {
"type": "string", "type": "string",
"description": "Suffix used for extensions built against the stable ABI.", "description": "Suffix used for extensions built against the stable ABI.\n\nThis field MUST be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing.",
"examples": [ "examples": [
".abi3.so" ".abi3.so"
] ]
@ -155,7 +157,7 @@
}, },
"suffixes": { "suffixes": {
"type": "object", "type": "object",
"description": "Valid module suffixes grouped by type.", "description": "Valid module suffixes grouped by type.\n\nThis section SHOULD be equivalent to the ``importlib.machinery.*_SUFFIXES`` attributes, if the implementation provides such suffixes. However, if the Python implementation does not provide suffixes of the kind specified by any of the attributes, the equivalent sub-section is not required to be present. Additionally, if a Python implementation provides extension kinds other than the ones listed on ``importlib.machinery`` module, they MAY add a sub-section for them.",
"examples": [ "examples": [
{ {
"source": [".py"], "source": [".py"],
@ -168,34 +170,34 @@
}, },
"libpython": { "libpython": {
"type": "object", "type": "object",
"description": "Object containing details related to the ``libpython`` library.\n\nIf the Python installation does not provide a ``libpython`` library, this section will be missing.", "description": "Object containing details related to the ``libpython`` library.\n\nThis section MUST by present if Python installation provides a ``libpython`` library, otherwise this section will be missing.",
"additionalProperties": false, "additionalProperties": false,
"properties": { "properties": {
"dynamic": { "dynamic": {
"type": "string", "type": "string",
"description": "The path to the dynamic ``libpython`` library.\n\nEither 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.", "description": "The path to the dynamic ``libpython`` library. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.\n\nThis field MUST be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing.",
"examples": [ "examples": [
"/usr/lib/libpython3.13.so.1.0", "/usr/lib/libpython3.14.so.1.0",
"lib/libpython3.13.so.1.0" "lib/libpython3.14.so.1.0"
] ]
}, },
"static": { "static": {
"type": "string", "type": "string",
"description": "The path to the static ``libpython`` library.\n\nEither 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.", "description": "The path to the static ``libpython`` library. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.\n\nThis field MUST be present if the Python installation provides a static ``libpython`` library, otherwise this entry will be missing.",
"examples": [ "examples": [
"/usr/lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a", "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
"lib/python3.13/config-3.13-x86_64-linux-gnu/libpython3.13.a" "lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a"
] ]
}, },
"link_to_libpython": { "link_to_libpython": {
"type": "boolean", "type": "boolean",
"description": "Should extensions built against a dynamic ``libpython`` link to it?" "description": "Should extensions built against a dynamic ``libpython`` link to it?\n\nThis field MUST be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing."
} }
} }
}, },
"c_api": { "c_api": {
"type": "object", "type": "object",
"description": "Object containing details related to the Python C API, if available.\n\nIf the Python implementation does not provide a C API, this section will be missing.", "description": "Object containing details related to the Python C API, if available.\n\nThis section MUST be present if the Python implementation provides a C API, otherwise this section will be missing.",
"required": [ "required": [
"headers" "headers"
], ],
@ -203,15 +205,15 @@
"properties": { "properties": {
"headers": { "headers": {
"type": "string", "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..", "description": "The path to the C API headers. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.",
"examples": [ "examples": [
"/usr/include/python3.13", "/usr/include/python3.14",
"include/python3.13" "include/python3.14"
] ]
}, },
"pkgconfig_path": { "pkgconfig_path": {
"type": "string", "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..", "description": "The path to the pkg-config definition files. Either an absolute path, or a relative path to the path defined in the ``base_prefix`` key.\n\nThis field MUST be present if the Python implementation provides pkg-config definition files for the C API, otherwise this section will be missing.",
"examples": [ "examples": [
"/usr/lib/pkgconfig", "/usr/lib/pkgconfig",
"lib/pkgconfig" "lib/pkgconfig"
@ -221,7 +223,7 @@
}, },
"arbitrary_data": { "arbitrary_data": {
"type": "object", "type": "object",
"description": "Object containing extra arbitrary data.\n\nThis is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification.", "description": "Object containing extra arbitrary data.\n\nThis is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implamentations may choose what data to provide in this section.",
"additionalProperties": true "additionalProperties": true
} }
} }