install report: docs

3 files changed, 165 insertions, 0 deletions

diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst
index 408ef25ff..384d393fd 100644
--- a/docs/html/cli/pip_install.rst
+++ b/docs/html/cli/pip_install.rst
@@ -79,6 +79,18 @@ for an exception regarding pre-release versions). Where more than one source of
 the chosen version is available, it is assumed that any source is acceptable
 (as otherwise the versions would differ).
 
+Obtaining information about what was installed
+----------------------------------------------
+
+The install command has a ``--report`` option that will generate a JSON report of what
+pip has installed. In combination with the ``--dry-run`` and ``--ignore-installed`` it
+can be used to *resolve* a set of requirements without actually installing them.
+
+The report can be written to a file, or to standard output (using ``--report -`` in
+combination with ``--quiet``).
+
+The format of the JSON report is described in :doc:`../reference/installation-report`.
+
 Installation Order
 ------------------
 
diff --git a/docs/html/reference/index.md b/docs/html/reference/index.md
index 855dc79b3..749e88096 100644
--- a/docs/html/reference/index.md
+++ b/docs/html/reference/index.md
@@ -9,4 +9,5 @@ interoperability standards that pip utilises/implements.
 build-system/index
 requirement-specifiers
 requirements-file-format
+installation-report
 ```
diff --git a/docs/html/reference/installation-report.md b/docs/html/reference/installation-report.md
new file mode 100644
index 000000000..0e46658e3
--- /dev/null
+++ b/docs/html/reference/installation-report.md
@@ -0,0 +1,152 @@
+# Installation Report
+
+The `--report` option of the pip install command produces a detailed JSON report of what
+it did install (or what it would have installed, if used with the `--dry-run` option).
+
+## Specification
+
+The report is a JSON object with the following properties:
+
+- `install`: an object where the properties are the canonicalized names of the
+  distribution packages (to be) installed and the values are of type
+  `InstallationReportItem` (see below).
+- `environment`: an object describing the environment where the installation report was
+  generated. See [PEP 508 environment
+  markers](https://peps.python.org/pep-0508/#environment-markers) for more information.
+  Values have a string type.
+
+An `InstallationReportItem` is an object describing a (to be) installed distribution
+package with the following properties:
+
+- `metadata`: the metadata of the distribution, converted to a JSON object according to
+  the [PEP 566
+  transformation](https://www.python.org/dev/peps/pep-0566/#json-compatible-metadata).
+
+- `is_direct`: `true` if the requirement was provided as, or constrained to, a direct
+  URL reference. `false` if the requirements was provided as a name and version
+  specifier.
+
+- `download_info`: Information about the artifact (to be) downloaded for installation,
+  using the [direct
+  URL](https://packaging.python.org/en/latest/specifications/direct-url/) data
+  structure. When `is_direct` is `true`, this field is the same as the `direct_url.json`
+  metadata, otherwise it represents the URL of the artifact obtained from the index or
+  `--find-links`.
+- `requested`: `true` if the requirement was explicitly provided by the user, either
+  directely via a command line argument or indirectly via a requirements file. `false`
+  if the requirement was installed as a dependency of another requirement.
+
+- `requested_extras`: extras requested by the user. This field is only present when the
+  `requested` field is true.
+
+## Example
+
+The following command:
+
+```console
+pip install \
+  --ignore-installed --dry-run --quiet \
+  --report - \
+  "pydantic>=1.9" git+https://github.com/pypa/packaging@main
+```
+
+will produce an output similar to this (metadata abriged for brevity):
+
+```json
+{
+  "install": {
+    "pydantic": {
+      "download_info": {
+        "url": "https://files.pythonhosted.org/packages/a4/0c/fbaa7319dcb5eecd3484686eb5a5c5702a6445adb566f01aee6de3369bc4/pydantic-1.9.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
+        "archive_info": {
+          "hash": "sha256=18f3e912f9ad1bdec27fb06b8198a2ccc32f201e24174cec1b3424dda605a310"
+        }
+      },
+      "is_direct": false,
+      "requested": true,
+      "metadata": {
+        "name": "pydantic",
+        "version": "1.9.1",
+        "requires_dist": [
+          "typing-extensions (>=3.7.4.3)",
+          "dataclasses (>=0.6) ; python_version < \"3.7\"",
+          "python-dotenv (>=0.10.4) ; extra == 'dotenv'",
+          "email-validator (>=1.0.3) ; extra == 'email'"
+        ],
+        "requires_python": ">=3.6.1",
+        "provides_extra": [
+          "dotenv",
+          "email"
+        ]
+      }
+    },
+    "packaging": {
+      "download_info": {
+        "url": "https://github.com/pypa/packaging",
+        "vcs_info": {
+          "vcs": "git",
+          "requested_revision": "main",
+          "commit_id": "4f42225e91a0be634625c09e84dd29ea82b85e27"
+        }
+      },
+      "is_direct": true,
+      "requested": true,
+      "metadata": {
+        "name": "packaging",
+        "version": "21.4.dev0",
+        "requires_dist": [
+          "pyparsing (!=3.0.5,>=2.0.2)"
+        ],
+        "requires_python": ">=3.7"
+      }
+    },
+    "pyparsing": {
+      "download_info": {
+        "url": "https://files.pythonhosted.org/packages/6c/10/a7d0fa5baea8fe7b50f448ab742f26f52b80bfca85ac2be9d35cdd9a3246/pyparsing-3.0.9-py3-none-any.whl",
+        "archive_info": {
+          "hash": "sha256=5026bae9a10eeaefb61dab2f09052b9f4307d44aee4eda64b309723d8d206bbc"
+        }
+      },
+      "is_direct": false,
+      "requested": false,
+      "metadata": {
+        "name": "pyparsing",
+        "version": "3.0.9",
+        "requires_dist": [
+          "railroad-diagrams ; extra == \"diagrams\"",
+          "jinja2 ; extra == \"diagrams\""
+        ],
+        "requires_python": ">=3.6.8"
+      }
+    },
+    "typing-extensions": {
+      "download_info": {
+        "url": "https://files.pythonhosted.org/packages/75/e1/932e06004039dd670c9d5e1df0cd606bf46e29a28e65d5bb28e894ea29c9/typing_extensions-4.2.0-py3-none-any.whl",
+        "archive_info": {
+          "hash": "sha256=6657594ee297170d19f67d55c05852a874e7eb634f4f753dbd667855e07c1708"
+        }
+      },
+      "is_direct": false,
+      "requested": false,
+      "metadata": {
+        "name": "typing_extensions",
+        "version": "4.2.0",
+        "requires_python": ">=3.7"
+      }
+    }
+  },
+  "environment": {
+    "implementation_name": "cpython",
+    "implementation_version": "3.10.5",
+    "os_name": "posix",
+    "platform_machine": "x86_64",
+    "platform_release": "5.13-generic",
+    "platform_system": "Linux",
+    "platform_version": "...",
+    "python_full_version": "3.10.5",
+    "platform_python_implementation": "CPython",
+    "python_version": "3.10",
+    "sys_platform": "linux"
+  }
+}
+```