PEP 739: first round of feedback (#3690)

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 <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
@@ -12,16 +13,16 @@ Python-Version: 3.13
 Abstract
 ========
 
-Introduce a standard format for a static description file to describe Python
+Introduce a standard format for a static description file with build details
-installations.
+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
+impossible. Having a static description file makes various of Python build
-installation details available without having to run the interpreter.
+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
+This PEP only defines a format. Python implementations may choose to include a
-installations, distributing such files is out of scope.
+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.
-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
+The standard Python build description format consists of the JSON representation
-representation of a dictionary with the with the following keys.
+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
+:Description: String representation the Python language version — a version
-              ``PY_VERSION`` macro on CPython.
+              string consisting only of the *major* and *minor* components (Eg.
-
+              ``3.13``).
-version_parts
-~~~~~~~~~~~~~
-
-:Type: ``object``
-:Description: Equivalent to :py:data:`sys.version_info`.
 
 implementation
 --------------
 
-Subsection with details related to Python implementation. While only the
+Subsection with details related to Python implementation. This section SHOULD be
-``name`` key is required in this section, this section SHOULD be equivalent to
+equivalent to :py:data:`sys.implementation` on most implementations, but only
-:py:data:`sys.implementation` on most implementations.
+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": "3.13"
-       "version_parts": {
+     },
+     "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
 =========