improve pooled progress output for BatchDownloader

- use more specific types for BatchDownloader#__call__
- calculate byte lengths with a HEAD request
- quiet all progress output from -q
- don't write colored output with --no-color
- write a lot more documentation for the new progress bar logic
- use ProgressBarType enum for --progress-bar CLI flag

news/12925.feature.rst

@@ -0,0 +1 @@
+Use very rich progress output for batch downloading. Use ``ProgressBarType`` enum class for ``--progress-bar`` choices.

src/pip/_internal/cli/cmdoptions.py

@@ -22,6 +22,7 @@
 from pip._vendor.packaging.utils import canonicalize_name
 
 from pip._internal.cli.parser import ConfigOptionParser
+from pip._internal.cli.progress_bars import ProgressBarType
 from pip._internal.exceptions import CommandError
 from pip._internal.locations import USER_CACHE_DIR, get_src_prefix
 from pip._internal.models.format_control import FormatControl
@@ -226,11 +227,15 @@ class PipOption(Option):
     "--progress-bar",
     dest="progress_bar",
     type="choice",
-    choices=["on", "off", "raw"],
-    default="on",
-    help="Specify whether the progress bar should be used [on, off, raw] (default: on)",
+    choices=ProgressBarType.choices(),
+    default=ProgressBarType.ON.value,
+    help=(
+        "Specify whether the progress bar should be used"
+        f" {ProgressBarType.help_choices()} (default: %default)"
+    ),
 )
 
+
 log: Callable[..., Option] = partial(
     PipOption,
     "--log",