Skip to content

Commit 0198eae

Browse files
sbidoulsbidoul
committed
install report: docs
1 parent 6eab8e4 commit 0198eae

File tree

3 files changed

+165
-0
lines changed

3 files changed

+165
-0
lines changed

‎docs/html/cli/pip_install.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,18 @@ for an exception regarding pre-release versions). Where more than one source of
7979
the chosen version is available, it is assumed that any source is acceptable
8080
(as otherwise the versions would differ).
8181

82+
Obtaining information about what was installed
83+
----------------------------------------------
84+
85+
The install command has a ``--report`` option that will generate a JSON report of what
86+
pip has installed. In combination with the ``--dry-run`` and ``--ignore-installed`` it
87+
can be used to *resolve* a set of requirements without actually installing them.
88+
89+
The report can be written to a file, or to standard output (using ``--report -`` in
90+
combination with ``--quiet``).
91+
92+
The format of the JSON report is described in :doc:`../reference/installation-report`.
93+
8294
Installation Order
8395
------------------
8496

‎docs/html/reference/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,5 @@ interoperability standards that pip utilises/implements.
99
build-system/index
1010
requirement-specifiers
1111
requirements-file-format
12+
installation-report
1213
```

‎docs/html/reference/installation-report.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Installation Report
2+
3+
The `--report` option of the pip install command produces a detailed JSON report of what
4+
it did install (or what it would have installed, if used with the `--dry-run` option).
5+
6+
## Specification
7+
8+
The report is a JSON object with the following properties:
9+
10+
- `install`: an object where the properties are the canonicalized names of the
11+
distribution packages (to be) installed and the values are of type
12+
`InstallationReportItem` (see below).
13+
- `environment`: an object describing the environment where the installation report was
14+
generated. See [PEP 508 environment
15+
markers](https://peps.python.org/pep-0508/#environment-markers) for more information.
16+
Values have a string type.
17+
18+
An `InstallationReportItem` is an object describing a (to be) installed distribution
19+
package with the following properties:
20+
21+
- `metadata`: the metadata of the distribution, converted to a JSON object according to
22+
the [PEP 566
23+
transformation](https://www.python.org/dev/peps/pep-0566/#json-compatible-metadata).
24+
25+
- `is_direct`: `true` if the requirement was provided as, or constrained to, a direct
26+
URL reference. `false` if the requirements was provided as a name and version
27+
specifier.
28+
29+
- `download_info`: Information about the artifact (to be) downloaded for installation,
30+
using the [direct
31+
URL](https://packaging.python.org/en/latest/specifications/direct-url/) data
32+
structure. When `is_direct` is `true`, this field is the same as the `direct_url.json`
33+
metadata, otherwise it represents the URL of the artifact obtained from the index or
34+
`--find-links`.
35+
- `requested`: `true` if the requirement was explicitly provided by the user, either
36+
directely via a command line argument or indirectly via a requirements file. `false`
37+
if the requirement was installed as a dependency of another requirement.
38+
39+
- `requested_extras`: extras requested by the user. This field is only present when the
40+
`requested` field is true.
41+
42+
## Example
43+
44+
The following command:
45+
46+
```console
47+
pip install \
48+
--ignore-installed --dry-run --quiet \
49+
--report - \
50+
"pydantic>=1.9" git+https://github.com/pypa/packaging@main
51+
```
52+
53+
will produce an output similar to this (metadata abriged for brevity):
54+
55+
```json
56+
{
57+
"install": {
58+
"pydantic": {
59+
"download_info": {
60+
"url": "https://files.pythonhosted.org/packages/a4/0c/fbaa7319dcb5eecd3484686eb5a5c5702a6445adb566f01aee6de3369bc4/pydantic-1.9.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
61+
"archive_info": {
62+
"hash": "sha256=18f3e912f9ad1bdec27fb06b8198a2ccc32f201e24174cec1b3424dda605a310"
63+
}
64+
},
65+
"is_direct": false,
66+
"requested": true,
67+
"metadata": {
68+
"name": "pydantic",
69+
"version": "1.9.1",
70+
"requires_dist": [
71+
"typing-extensions (>=3.7.4.3)",
72+
"dataclasses (>=0.6) ; python_version < \"3.7\"",
73+
"python-dotenv (>=0.10.4) ; extra == 'dotenv'",
74+
"email-validator (>=1.0.3) ; extra == 'email'"
75+
],
76+
"requires_python": ">=3.6.1",
77+
"provides_extra": [
78+
"dotenv",
79+
"email"
80+
]
81+
}
82+
},
83+
"packaging": {
84+
"download_info": {
85+
"url": "https://github.com/pypa/packaging",
86+
"vcs_info": {
87+
"vcs": "git",
88+
"requested_revision": "main",
89+
"commit_id": "4f42225e91a0be634625c09e84dd29ea82b85e27"
90+
}
91+
},
92+
"is_direct": true,
93+
"requested": true,
94+
"metadata": {
95+
"name": "packaging",
96+
"version": "21.4.dev0",
97+
"requires_dist": [
98+
"pyparsing (!=3.0.5,>=2.0.2)"
99+
],
100+
"requires_python": ">=3.7"
101+
}
102+
},
103+
"pyparsing": {
104+
"download_info": {
105+
"url": "https://files.pythonhosted.org/packages/6c/10/a7d0fa5baea8fe7b50f448ab742f26f52b80bfca85ac2be9d35cdd9a3246/pyparsing-3.0.9-py3-none-any.whl",
106+
"archive_info": {
107+
"hash": "sha256=5026bae9a10eeaefb61dab2f09052b9f4307d44aee4eda64b309723d8d206bbc"
108+
}
109+
},
110+
"is_direct": false,
111+
"requested": false,
112+
"metadata": {
113+
"name": "pyparsing",
114+
"version": "3.0.9",
115+
"requires_dist": [
116+
"railroad-diagrams ; extra == \"diagrams\"",
117+
"jinja2 ; extra == \"diagrams\""
118+
],
119+
"requires_python": ">=3.6.8"
120+
}
121+
},
122+
"typing-extensions": {
123+
"download_info": {
124+
"url": "https://files.pythonhosted.org/packages/75/e1/932e06004039dd670c9d5e1df0cd606bf46e29a28e65d5bb28e894ea29c9/typing_extensions-4.2.0-py3-none-any.whl",
125+
"archive_info": {
126+
"hash": "sha256=6657594ee297170d19f67d55c05852a874e7eb634f4f753dbd667855e07c1708"
127+
}
128+
},
129+
"is_direct": false,
130+
"requested": false,
131+
"metadata": {
132+
"name": "typing_extensions",
133+
"version": "4.2.0",
134+
"requires_python": ">=3.7"
135+
}
136+
}
137+
},
138+
"environment": {
139+
"implementation_name": "cpython",
140+
"implementation_version": "3.10.5",
141+
"os_name": "posix",
142+
"platform_machine": "x86_64",
143+
"platform_release": "5.13-generic",
144+
"platform_system": "Linux",
145+
"platform_version": "...",
146+
"python_full_version": "3.10.5",
147+
"platform_python_implementation": "CPython",
148+
"python_version": "3.10",
149+
"sys_platform": "linux"
150+
}
151+
}
152+
```

0 commit comments

Comments
 (0)