specifications: add build-details.json (PEP 739)

.github/CODEOWNERS

@@ -1,2 +1,6 @@
 source/guides/github-actions-ci-cd-sample/* @webknjaz
 source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst @webknjaz
+
+# build-details.json
+source/specifications/build-details/ @FFY00
+source/specifications/specs/build-details-*.json @FFY00

requirements.txt

@@ -4,3 +4,4 @@ sphinx-autobuild==2021.3.14
 sphinx-inline-tabs==2023.4.21
 sphinx-copybutton==0.5.2
 sphinx-toolbox==3.5.0
+sphinx-jsonschema==1.19.1

source/conf.py

@@ -28,6 +28,7 @@
     "sphinx_inline_tabs",
     "sphinx_copybutton",
     "sphinx_toolbox.collapse",
+    "sphinx-jsonschema",
 ]
 
 nitpicky = True
@@ -82,6 +83,10 @@
     # https://plausible.io/packaging.python.org
     html_js_files.extend(_metrics_js_files)
 
+html_extra_path = [
+    "specifications/schemas",
+]
+
 # -- Options for HTML help output ------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output
 
@@ -128,6 +133,7 @@
 
 linkcheck_ignore = [
     "http://localhost:\\d+",
+    "https://packaging.python.org/en/latest/specifications/schemas/.*",
     "https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
     "https://pypi.org/manage/*",
     "https://test.pypi.org/manage/*",

source/specifications/build-details/examples/build-details-v1.0.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": "1.0",
+  "base_prefix": "/usr",
+  "base_interpreter": "/usr/bin/python",
+  "platform": "linux-x86_64",
+  "language": {
+    "version": "3.14",
+    "version_info": {
+      "major": 3,
+      "minor": 14,
+      "micro": 0,
+      "releaselevel": "alpha",
+      "serial": 0
+    }
+  },
+  "implementation": {
+    "name": "cpython",
+    "version": {
+      "major": 3,
+      "minor": 14,
+      "micro": 0,
+      "releaselevel": "alpha",
+      "serial": 0
+    },
+    "hexversion": 51249312,
+    "cache_tag": "cpython-314",
+    "_multiarch": "x86_64-linux-gnu"
+  },
+  "abi": {
+    "flags": ["t", "d"],
+    "extension_suffix": ".cpython-314-x86_64-linux-gnu.so",
+    "stable_abi_suffix": ".abi3.so"
+  },
+  "suffixes": {
+    "source": [".py"],
+    "bytecode": [".pyc"],
+    "optimized_bytecode": [".pyc"],
+    "debug_bytecode": [".pyc"],
+    "extensions": [".cpython-314-x86_64-linux-gnu.so", ".abi3.so", ".so"]
+  },
+  "libpython": {
+    "dynamic": "/usr/lib/libpython3.14.so.1.0",
+    "dynamic_stableabi": "/usr/lib/libpython3.so",
+    "static": "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
+    "link_extensions": true
+  },
+  "c_api": {
+    "headers": "/usr/include/python3.14",
+    "pkgconfig_path": "/usr/lib/pkgconfig"
+  }
+}

source/specifications/build-details/index.rst

@@ -0,0 +1,52 @@
+.. _build-details:
+
+==========================
+:file:`build-details.json`
+==========================
+
+.. toctree::
+   :hidden:
+
+   v1.0 <v1.0>
+
+
+The ``build-details.json`` file is a standardized file format that provides
+build-specfic information of a Python installation, such as its version,
+extension ABI details, and other information that is specific to that particular
+build of Python.
+
+Starting from Python 3.14, a ``build-details.json`` file is installed in the
+platform-independent standard library directory (``stdlib``, e.g.
+``/usr/lib/python3.14/build-details.json``).
+
+Please refer to the :ref:`latest version <build-details-v1.0>` for its
+specification.
+
+..
+   Update to point to the latest version!
+
+.. literalinclude:: examples/build-details-v1.0.json
+   :caption: Example
+   :language: json
+   :linenos:
+
+
+Changelog
+---------
+
+..
+   Order in decreasing order.
+
+v1.0
+~~~~
+
+.. list-table::
+
+    * - Specification
+      - :ref:`build-details-v1.0`
+
+    * - Schema
+      - :download:`https://packaging.python.org/en/latest/specifications/schemas/build-details-v1.0.schema.json <../schemas/build-details-v1.0.schema.json>`
+
+
+- Initial version, introduced by :pep:`739`.

source/specifications/build-details/v1.0.rst

@@ -0,0 +1,18 @@
+.. _build-details-v1.0:
+
+===========================
+``build-details.json`` v1.0
+===========================
+
+
+Specification
+-------------
+
+.. jsonschema:: ../schemas/build-details-v1.0.schema.json
+    :lift_title: false
+
+
+Example
+-------
+
+.. literalinclude:: examples/build-details-v1.0.json

source/specifications/index.rst

@@ -15,3 +15,4 @@ and for proposing new ones, is documented on
    section-installation-metadata
    section-distribution-formats
    section-package-indices
+   section-python-description-formats