diff --git a/peps/pep-0739.rst b/peps/pep-0739.rst index 54c825190..bad1ddd9f 100644 --- a/peps/pep-0739.rst +++ b/peps/pep-0739.rst @@ -1,7 +1,8 @@ PEP: 739 -Title: Static description file for Python installations +Title: Static description file for build details of Python installations Author: Filipe Laíns PEP-Delegate: Paul Moore +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 @@ -12,16 +13,16 @@ Python-Version: 3.13 Abstract ======== -Introduce a standard format for a static description file to describe Python -installations. +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 -installation details available without having to run the interpreter. +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. @@ -29,52 +30,46 @@ 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. +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 installation description format consists of the JSON -representation of a dictionary with the with the following keys. +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 +: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. + 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 language specification. +Subsection with details related to the Python 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`. +: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. While only the -``name`` key is required in this section, this section SHOULD be equivalent to -:py:data:`sys.implementation` on most implementations. +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 ~~~~ @@ -82,6 +77,13 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -114,25 +116,42 @@ Example { "schema_version": 1, "language": { - "version": "3.13.1", - "version_parts": { + "version": "3.13" + }, + "implementation": { + "name": "cpython", + "version": { "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": { + }, + "libpython": { } } + +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 =========