Skip to content

Commit 360e1d8

Browse files
sbidoulsbidoul
committed
install report: docs
1 parent 00f374c commit 360e1d8

File tree

3 files changed

+162
-0
lines changed

3 files changed

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

0 commit comments

Comments
 (0)