Merge branch 'main' into add-docs-for-platform-and-python-version

Author: Shepard2154

docs/html/conf.py

@@ -14,20 +14,29 @@
 # -- General configuration ------------------------------------------------------------
 
 extensions = [
-    # first-party extensions
-    "sphinx.ext.autodoc",
-    "sphinx.ext.todo",
-    "sphinx.ext.intersphinx",
-    # our extensions
+    # extensions common to all builds
     "pip_sphinxext",
-    # third-party extensions
-    "myst_parser",
-    "sphinx_copybutton",
-    "sphinx_inline_tabs",
-    "sphinxcontrib.towncrier",
-    "sphinx_issues",
 ]
 
+# 'tags' is a injected by sphinx
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-tags
+if "man" not in tags:  # type: ignore[name-defined] # noqa: F821
+    # extensions not needed for building man pages
+    extensions.extend(
+        (
+            # first-party extensions
+            "sphinx.ext.autodoc",
+            "sphinx.ext.todo",
+            "sphinx.ext.intersphinx",
+            # third-party extensions
+            "myst_parser",
+            "sphinx_copybutton",
+            "sphinx_inline_tabs",
+            "sphinxcontrib.towncrier",
+            "sphinx_issues",
+        ),
+    )
+
 # General information about the project.
 project = "pip"
 copyright = "The pip developers"

news/12963.feature.rst

@@ -1,4 +1,4 @@
-- Add a ``--group`` option which allows installation from PEP 735 Dependency
-  Groups. ``--group`` accepts arguments of the form ``group`` or
-  ``path:group``, where the default path is ``pyproject.toml``, and installs
-  the named Dependency Group from the provided ``pyproject.toml`` file.
+Add a ``--group`` option which allows installation from :pep:`735` Dependency
+Groups. ``--group`` accepts arguments of the form ``group`` or
+``path:group``, where the default path is ``pyproject.toml``, and installs
+the named Dependency Group from the provided ``pyproject.toml`` file.

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.

news/13168.doc.rst

@@ -0,0 +1,3 @@
+Added support for building only the man pages with minimal dependencies using
+the sphinx-build ``--tag man`` option. This enables distributors to generate man
+pages without requiring HTML documentation dependencies.

news/13318.removal.rst

@@ -0,0 +1,4 @@
+A warning is emitted when the deprecated ``pkg_resources`` library is used to
+inspect and discover installed packages. This warning should only be visible to
+users who set an undocumented environment variable to disable the default
+``importlib.metadata`` backend.

noxfile.py

@@ -145,6 +145,7 @@ def get_sphinx_build_command(kind: str) -> List[str]:
         return [
             "sphinx-build",
             "--keep-going",
+            "--tag", kind,
             "-W",
             "-c", "docs/html",  # see note above
             "-d", "docs/build/doctrees/" + kind,

src/pip/_internal/cli/cmdoptions.py

@@ -281,8 +281,17 @@ class PipOption(Option):
     dest="retries",
     type="int",
     default=5,
-    help="Maximum number of retries each connection should attempt "
-    "(default %default times).",
+    help="Maximum attempts to establish a new HTTP connection. (default: %default)",
+)
+
+resume_retries: Callable[..., Option] = partial(
+    Option,
+    "--resume-retries",
+    dest="resume_retries",
+    type="int",
+    default=0,
+    help="Maximum attempts to resume or restart an incomplete download. "
+    "(default: %default)",
 )
 
 timeout: Callable[..., Option] = partial(
@@ -1077,7 +1086,6 @@ def check_list_path_option(options: Values) -> None:
     help=("Enable deprecated functionality, that will be removed in the future."),
 )
 
-
 ##########
 # groups #
 ##########
@@ -1110,6 +1118,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

@@ -29,6 +29,7 @@ def _rich_download_progress_bar(
     *,
     bar_type: str,
     size: Optional[int],
+    initial_progress: Optional[int] = None,
 ) -> Generator[bytes, None, None]:
     assert bar_type == "on", "This should only be used in the default mode."
 
@@ -54,6 +55,8 @@ def _rich_download_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
@@ -86,12 +89,13 @@ def _raw_progress_bar(
     iterable: Iterable[bytes],
     *,
     size: Optional[int],
+    initial_progress: Optional[int] = None,
 ) -> Generator[bytes, None, None]:
     def write_progress(current: int, total: int) -> None:
         sys.stdout.write(f"Progress {current} of {total}\n")
         sys.stdout.flush()
 
-    current = 0
+    current = initial_progress or 0
     total = size or 0
     rate_limiter = RateLimiter(0.25)
 
@@ -105,18 +109,25 @@ 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
 ) -> ProgressRenderer[bytes]:
     """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_download_progress_bar, bar_type=bar_type, size=size
+            _rich_download_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

@@ -144,6 +144,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

@@ -27,6 +27,7 @@
     from pip._vendor.requests.models import Request, Response
 
     from pip._internal.metadata import BaseDistribution
+    from pip._internal.models.link import Link
     from pip._internal.req.req_install import InstallRequirement
 
 logger = logging.getLogger(__name__)
@@ -809,6 +810,38 @@ def __init__(
         )
 
 
+class IncompleteDownloadError(DiagnosticPipError):
+    """Raised when the downloader receives fewer bytes than advertised
+    in the Content-Length header."""
+
+    reference = "incomplete-download"
+
+    def __init__(
+        self, link: "Link", received: int, expected: int, *, retries: int
+    ) -> None:
+        # Dodge circular import.
+        from pip._internal.utils.misc import format_size
+
+        download_status = f"{format_size(received)}/{format_size(expected)}"
+        if retries:
+            retry_status = f"after {retries} attempts "
+            hint = "Use --resume-retries to configure resume attempt limit."
+        else:
+            retry_status = ""
+            hint = "Consider using --resume-retries to enable download resumption."
+        message = Text(
+            f"Download failed {retry_status}because not enough bytes "
+            f"were received ({download_status})"
+        )
+
+        super().__init__(
+            message=message,
+            context=f"URL: {link.redacted_url}",
+            hint_stmt=hint,
+            note_stmt="This is an issue with network connectivity, not pip.",
+        )
+
+
 class ResolutionTooDeepError(DiagnosticPipError):
     """Raised when the dependency resolver exceeds the maximum recursion depth."""