rearrange explanatory comments

src/pip/_internal/network/lazy_wheel.py

@@ -40,22 +40,24 @@ def dist_from_wheel_url(name: str, url: str, session: Session) -> BaseDistributi
     is raised.
     """
     try:
+        # After context manager exit, wheel.name will point to a deleted file path.
+        # Add `delete_backing_file=False` to disable this for debugging.
         with LazyHTTPFile(url, session) as lazy_file:
-            with indent_log():
-                logger.debug("begin prefetching for %s", name)
-                lazy_file.prefetch_contiguous_dist_info(name)
-                logger.debug("done prefetching for %s", name)
+            lazy_file.prefetch_contiguous_dist_info(name)
 
-            # For read-only ZIP files, ZipFile only needs methods read,
-            # seek, seekable and tell, not the whole IO protocol.
             wheel = MemoryWheel(lazy_file.name, lazy_file)
-            # After context manager exit, wheel.name is an invalid file by intention.
             return get_wheel_distribution(wheel, canonicalize_name(name))
     except (BadZipFile, UnsupportedWheel):
         raise InvalidWheel(url, name)
 
 
 class ReadOnlyIOWrapper(BinaryIO):
+    """Implement read-side ``BinaryIO`` methods wrapping an inner ``BinaryIO``.
+
+    For read-only ZIP files, ``ZipFile`` only needs read, seek, seekable, and tell.
+    ``LazyHTTPFile`` subclasses this and therefore must only implement its lazy read().
+    """
+
     _file: BinaryIO
 
     def __init__(self, inner: BinaryIO) -> None:
@@ -160,8 +162,8 @@ def __next__(self) -> bytes:
 # guess at how the server will interpret caching directives for range requests (we
 # especially don't want the server to return 200 OK with the entire file contents).
 # TODO: consider If-Match (etag) and handling 304 File Modified, here or in the
-#       unpack_url() method.
-_UNCACHED_HEADERS = {**HEADERS, 'Cache-Control': 'no-cache'}
+#       unpack_url() method for non-lazy downloads.
+_UNCACHED_HEADERS = {**HEADERS, "Cache-Control": "no-cache"}
 
 
 class LazyHTTPFile(ReadOnlyIOWrapper):
@@ -182,9 +184,9 @@ def __init__(
         url: str,
         session: Session,
         initial_chunk_size: int = _DEFAULT_INITIAL_FETCH,
+        delete_backing_file: bool = True,
     ) -> None:
-        # Add delete=False and print the file's `.name` to debug invalid virtual zips.
-        super().__init__(cast(BinaryIO, NamedTemporaryFile()))
+        super().__init__(cast(BinaryIO, NamedTemporaryFile(delete=delete_backing_file)))
 
         self._request_count = 0
         self._session = session
@@ -387,16 +389,27 @@ def _download(self, start: int, end: int) -> None:
                     self._file.write(chunk)
 
     def prefetch_contiguous_dist_info(self, name: str) -> None:
-        """
-        Read contents of entire dist-info section of wheel.
+        """Read contents of entire dist-info section of wheel.
 
-        pip will read every entry in this directory when generating a dist from a wheel,
-        so prepopulating the file contents avoids waiting for multiple range requests.
+        We know pip will read every entry in this directory when generating a dist from
+        a wheel, so prepopulating the file contents avoids waiting for further
+        range requests.
         """
+        # Clarify in debug output which requests were sent during __init__, which during
+        # the prefetch, and which during the dist metadata generation.
+        with indent_log():
+            logger.debug("begin prefetching dist-info for %s", name)
+            self._prefetch_contiguous_dist_info(name)
+            logger.debug("done prefetching dist-info for %s", name)
+
+    def _prefetch_contiguous_dist_info(self, name: str) -> None:
         dist_info_prefix = re.compile(r"^[^/]*\.dist-info/")
         start: int | None = None
         end: int | None = None
 
+        # This may perform further requests if __init__() did not pull in the entire
+        # central directory at the end of the file (although _DEFAULT_INITIAL_FETCH
+        # should be set large enough to avoid this).
         zf = ZipFile(self)
 
         for info in zf.infolist():
@@ -405,12 +418,14 @@ def prefetch_contiguous_dist_info(self, name: str) -> None:
                     start = info.header_offset
                     continue
             else:
+                # The last .dist-info/ entry may be before the end of the file if the
+                # wheel's entries are sorted lexicographically (which is unusual).
                 if not dist_info_prefix.search(info.filename):
                     end = info.header_offset
                     break
         if start is None:
             raise UnsupportedWheel(
-                f"no {dist_info_prefix} directory found for {name} in {self.name}"
+                f"no {dist_info_prefix!r} directory found for {name} in {self.name}"
             )
         # If the last entries of the zip are the .dist-info/ dir (as usual), then give
         # us everything until the start of the central directory.