Introduce resumable downloads with --resume-retries

news/12991.feature.rst

@@ -0,0 +1,3 @@
+Add support to enable resuming incomplete downloads.
+
+Control the number of retry attempts using the ``--resume-retries`` flag.

src/pip/_internal/cli/cmdoptions.py

@@ -1028,6 +1028,15 @@ def check_list_path_option(options: Values) -> None:
     help=("Enable deprecated functionality, that will be removed in the future."),
 )
 
+resume_retries: Callable[..., Option] = partial(
+    Option,
+    "--resume-retries",
+    dest="resume_retries",
+    type="int",
+    default=0,
+    help="Maximum number of resumption retries for incomplete downloads"
+    "(default %default times).",
+)
 
 ##########
 # groups #
@@ -1061,6 +1070,7 @@ def check_list_path_option(options: Values) -> None:
         no_python_version_warning,
         use_new_feature,
         use_deprecated_feature,
+        resume_retries,
     ],
 }
 

src/pip/_internal/cli/progress_bars.py

@@ -26,6 +26,7 @@ def _rich_progress_bar(
     *,
     bar_type: str,
     size: int,
+    initial_progress: Optional[int] = None,
 ) -> Generator[bytes, None, None]:
     assert bar_type == "on", "This should only be used in the default mode."
 
@@ -51,6 +52,8 @@ def _rich_progress_bar(
 
     progress = Progress(*columns, refresh_per_second=5)
     task_id = progress.add_task(" " * (get_indentation() + 2), total=total)
+    if initial_progress is not None:
+        progress.update(task_id, advance=initial_progress)
     with progress:
         for chunk in iterable:
             yield chunk
@@ -80,15 +83,24 @@ def write_progress(current: int, total: int) -> None:
 
 
 def get_download_progress_renderer(
-    *, bar_type: str, size: Optional[int] = None
+    *, bar_type: str, size: Optional[int] = None, initial_progress: Optional[int] = None
 ) -> DownloadProgressRenderer:
     """Get an object that can be used to render the download progress.
 
     Returns a callable, that takes an iterable to "wrap".
     """
     if bar_type == "on":
-        return functools.partial(_rich_progress_bar, bar_type=bar_type, size=size)
+        return functools.partial(
+            _rich_progress_bar,
+            bar_type=bar_type,
+            size=size,
+            initial_progress=initial_progress,
+        )
     elif bar_type == "raw":
-        return functools.partial(_raw_progress_bar, size=size)
+        return functools.partial(
+            _raw_progress_bar,
+            size=size,
+            initial_progress=initial_progress,
+        )
     else:
         return iter  # no-op, when passed an iterator

src/pip/_internal/cli/req_command.py

@@ -142,6 +142,7 @@ def make_requirement_preparer(
             lazy_wheel=lazy_wheel,
             verbosity=verbosity,
             legacy_resolver=legacy_resolver,
+            resume_retries=options.resume_retries,
         )
 
     @classmethod

src/pip/_internal/exceptions.py

@@ -775,3 +775,24 @@ def __init__(self, *, distribution: "BaseDistribution") -> None:
             ),
             hint_stmt=None,
         )
+
+
+class IncompleteDownloadError(DiagnosticPipError):
+    """Raised when the downloader receives fewer bytes than advertised
+    in the Content-Length header."""
+
+    reference = "incomplete-download-error"
+
+    def __init__(self, link: str, resume_retries: int) -> None:
+        message = (
+            f"Download failed after {resume_retries} attempts because not enough"
+            " bytes were received. The incomplete file has been cleaned up."
+        )
+        hint = "Use --resume-retries to configure resume retry limit."
+
+        super().__init__(
+            message=message,
+            context=f"File: {link}\nResume retry limit: {resume_retries}",
+            hint_stmt=hint,
+            note_stmt="This is an issue with network connectivity, not pip.",
+        )