Add machine readable download progress option

docs/html/user_guide.rst

@@ -855,6 +855,20 @@ We are using `freeze`_ here which outputs installed packages in requirements for
 
   reqs = subprocess.check_output([sys.executable, '-m', 'pip', 'freeze'])
 
+Since pip's progress bar gets hidden when running in a subprocess, you can use
+the ``--progress-bar=json`` option for easily parsable progress information::
+
+  subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'my_package', '--progress-bar=json'])
+
+Which will give the following output after it processes each download chunk:
+
+``PROGRESS:{"current": ######, "total": ######}``
+
+Here, ``PROGRESS:`` indicates it is download progress. The rest of the message is JSON
+with the ``current`` number of bytes downloaded and ``total`` .whl size as key/value pairs.
+This can be used to build your own progress bar, or report progress in other ways.
+This feature cannot be used unless pip is invoked in a subprocess.
+
 If you don't want to use pip's command line functionality, but are rather
 trying to implement code that works with Python packages, their metadata, or
 PyPI, then you should consider other, supported, packages that offer this type

news/11508.feature.rst

@@ -0,0 +1 @@
+Add a new progress_bar type that allows machine-readable (json) download progress

src/pip/_internal/cli/cmdoptions.py

@@ -226,9 +226,12 @@ class PipOption(Option):
     "--progress-bar",
     dest="progress_bar",
     type="choice",
-    choices=["on", "off"],
+    choices=["on", "off", "json"],
     default="on",
-    help="Specify whether the progress bar should be used [on, off] (default: on)",
+    help=(
+        "Specify whether the progress bar should be used"
+        " [on, off, json] (default: on)"
+    ),
 )
 
 log: Callable[..., Option] = partial(

src/pip/_internal/cli/progress_bars.py

@@ -1,4 +1,7 @@
 import functools
+import json
+import logging
+import sys
 from typing import Callable, Generator, Iterable, Iterator, Optional, Tuple
 
 from pip._vendor.rich.progress import (
@@ -16,6 +19,8 @@
 
 from pip._internal.utils.logging import get_indentation
 
+logger = logging.getLogger(__name__)
+
 DownloadProgressRenderer = Callable[[Iterable[bytes]], Iterator[bytes]]
 
 
@@ -55,6 +60,29 @@ def _rich_progress_bar(
             progress.update(task_id, advance=len(chunk))
 
 
+class _MachineReadableProgress:
+    def __init__(self, iterable: Iterable[bytes], size: Optional[int]) -> None:
+        self._iterable = iter(iterable)
+        self._size = size
+        self._progress = 0
+
+    def __iter__(self) -> Iterator[bytes]:
+        return self
+
+    def __next__(self) -> bytes:
+        chunk = next(self._iterable)
+        self._progress += len(chunk)
+        progress_info = {
+            "current": self._progress,
+            "total": self._size,
+        }
+        logger.info(
+            "PROGRESS:%s",
+            json.dumps(progress_info),
+        )
+        return chunk
+
+
 def get_download_progress_renderer(
     *, bar_type: str, size: Optional[int] = None
 ) -> DownloadProgressRenderer:
@@ -64,5 +92,12 @@ def get_download_progress_renderer(
     """
     if bar_type == "on":
         return functools.partial(_rich_progress_bar, bar_type=bar_type, size=size)
+    elif bar_type == "json":
+        # We don't want regular users to use this progress_bar type
+        # so only use if not a TTY
+        assert (
+            not sys.stdout.isatty()
+        ), 'The "json" progress_bar type should only be used inside subprocesses.'
+        return functools.partial(_MachineReadableProgress, size=size)
     else:
         return iter  # no-op, when passed an iterator

tests/functional/test_install_progress.py

@@ -0,0 +1,42 @@
+import pytest
+from tests.lib import (
+    PipTestEnvironment,
+)
+import subprocess
+
+
+@pytest.mark.network
+def test_install_with_json_progress_cli(script: PipTestEnvironment) -> None:
+    """
+    Test installing a package using pip install --progress-bar=json
+    but not as a subprocess
+    """
+    result = script.pip(
+        "install",
+        "opencv-python",
+        "--progress-bar=json",
+        expect_error=True,
+    )
+    assert (
+        'The "json" progress_bar type should only be used inside subprocesses.'
+        in result.stderr
+    )
+
+
+@pytest.mark.network
+def test_install_with_json_progress_subproc(_script: PipTestEnvironment) -> None:
+    """
+    Test installing a package using pip install --progress-bar=json
+    but not as a subprocess
+    """
+    result = subprocess.check_output(
+        [
+            "python",
+            "-m",
+            "pip",
+            "install",
+            "opencv-python",
+            "--progress-bar=json",
+        ]
+    )
+    assert "PROGRESS:" in result.decode("utf-8")