zipwire 0.2.0__tar.gz → 0.3.0__tar.gz

{zipwire-0.2.0 → zipwire-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zipwire
-Version: 0.2.0
+Version: 0.3.0
 Summary: Read and extract files from remote ZIP archives over HTTP range requests
 Project-URL: Homepage, https://github.com/tiran/zipwire
 Project-URL: Documentation, https://zipwire.readthedocs.io/

{zipwire-0.2.0 → zipwire-0.3.0}/docs/api.rst

@@ -18,12 +18,27 @@ Core
 
 .. autoclass:: zipwire.SyncRemoteZip
    :members:
+   :inherited-members:
    :special-members: __enter__, __exit__
 
 .. autoclass:: zipwire.AsyncRemoteZip
    :members:
+   :inherited-members:
    :special-members: __aenter__, __aexit__
 
+Wheel
+-----
+
+.. autoclass:: zipwire.SyncRemoteWheel
+   :members:
+   :inherited-members:
+   :show-inheritance:
+
+.. autoclass:: zipwire.AsyncRemoteWheel
+   :members:
+   :inherited-members:
+   :show-inheritance:
+
 .. autoclass:: zipwire.RemoteZipInfo
    :show-inheritance:
 

{zipwire-0.2.0 → zipwire-0.3.0}/docs/quickstart.rst

@@ -83,7 +83,7 @@ Async with httpx2
    async def main():
        reader = Httpx2AsyncReader("https://archive.example/data.zip")
        async with AsyncRemoteZip(reader) as rz:
-           names = await rz.namelist()
+           names = rz.namelist()
            print(names)
 
 
@@ -109,6 +109,47 @@ Async streaming to disk
 
    asyncio.run(main())
 
+Wheel dist-info metadata
+------------------------
+
+``SyncRemoteWheel`` and ``AsyncRemoteWheel`` extend the base classes
+with an adaptive tail fetch and a ``distinfolist()`` method.  The tail
+size scales with the archive (at least 128 KiB, up to ~0.4% of the
+file) so that dist-info entries are typically served from memory
+without extra HTTP requests.
+
+.. code-block:: python
+
+   from zipwire import SyncRemoteWheel
+   from zipwire.backends import Urllib3Reader
+
+   url = "https://files.pythonhosted.org/.../requests-2.32.3-py3-none-any.whl"
+   reader = Urllib3Reader(url)
+   with SyncRemoteWheel(reader) as whl:
+       for entry in whl.distinfolist():
+           data = whl.read(entry)
+           print(entry.filename, len(data))
+
+Async variant:
+
+.. code-block:: python
+
+   import asyncio
+
+   from zipwire import AsyncRemoteWheel
+   from zipwire.backends import AiohttpReader
+
+
+   async def main():
+       reader = AiohttpReader(url)
+       async with AsyncRemoteWheel(reader) as whl:
+           for entry in whl.distinfolist():
+               data = await whl.read(entry)
+               print(entry.filename, len(data))
+
+
+   asyncio.run(main())
+
 Passing a pre-configured client
 --------------------------------
 

{zipwire-0.2.0 → zipwire-0.3.0}/src/zipwire/__init__.py

@@ -34,7 +34,7 @@ Asynchronous example
     async def main():
         reader = AiohttpReader("https://example.com/archive.zip")
         async with AsyncRemoteZip(reader) as rz:
-            print(await rz.namelist())
+            print(rz.namelist())
             data = await rz.read("path/inside/archive.txt")
 
             # Stream a large entry directly to disk
@@ -58,6 +58,27 @@ Asynchronous:
   - ``AiohttpReader`` -- uses *aiohttp* (``pip install zipwire[aiohttp]``)
   - ``Httpx2AsyncReader`` -- uses *httpx2*, supports HTTP/2
     (``pip install zipwire[httpx2]``)
+
+Wheel subclasses
+----------------
+
+``SyncRemoteWheel`` and ``AsyncRemoteWheel`` extend the base classes
+for Python wheels.  They parse the wheel URL to derive the
+``.dist-info`` directory name, fetch an adaptive tail (at least
+128 KiB, scaling with archive size) to cover dist-info entries at
+the end of the archive, and serve matching reads from the tail
+buffer without extra HTTP requests.
+
+::
+
+    from zipwire import SyncRemoteWheel
+    from zipwire.backends import Urllib3Reader
+
+    url = "https://files.pythonhosted.org/.../requests-2.32.3-py3-none-any.whl"
+    reader = Urllib3Reader(url)
+    with SyncRemoteWheel(reader) as whl:
+        for entry in whl.distinfolist():
+            print(entry.filename, whl.read(entry))
 """
 
 from __future__ import annotations
@@ -76,10 +97,12 @@ from zipwire._errors import (
 from zipwire._parser import EOCDInfo
 from zipwire._sync import SyncRemoteZip
 from zipwire._types import AsyncReader, Headers, SyncReader, Writable
+from zipwire._wheel import AsyncRemoteWheel, SyncRemoteWheel
 from zipwire._zipinfo import RemoteZipInfo
 
 __all__ = [
     "AsyncReader",
+    "AsyncRemoteWheel",
     "AsyncRemoteZip",
     "BadZipFile",
     "CRCMismatch",
@@ -91,6 +114,7 @@ __all__ = [
     "RangeRequestUnsupported",
     "RemoteZipInfo",
     "SyncReader",
+    "SyncRemoteWheel",
     "SyncRemoteZip",
     "UnsupportedCompression",
     "Writable",

{zipwire-0.2.0 → zipwire-0.3.0}/src/zipwire/__main__.py

@@ -41,7 +41,7 @@ async def _run_async(url: str, backend: str, skip_dirs: bool) -> None:
     names = {"httpx2": "Httpx2AsyncReader", "aiohttp": "AiohttpReader"}
     reader_cls = getattr(backends, names[backend])
     async with AsyncRemoteZip(reader_cls(url)) as rz:
-        _print_table(await rz.infolist(), skip_dirs)
+        _print_table(rz.infolist(), skip_dirs)
 
 
 def main(argv: list[str] | None = None) -> None:

{zipwire-0.2.0 → zipwire-0.3.0}/src/zipwire/_async.py

@@ -4,29 +4,22 @@ from __future__ import annotations
 
 import typing
 
+from zipwire._base import RemoteZipBase
 from zipwire._constants import (
     LOCAL_FILE_HEADER_SIZE,
-    MAX_EOCD_SEARCH,
     PREFETCH_EXTRA,
     PREFETCH_THRESHOLD,
 )
 from zipwire._decompress import StreamingDecompressor, decompress
-from zipwire._errors import FileNotFoundInZip, FileTooLarge, RangeRequestUnsupported
-from zipwire._parser import (
-    EOCDInfo,
-    find_eocd,
-    parse_central_directory,
-    parse_local_file_header,
-)
+from zipwire._errors import FileTooLarge, RangeRequestUnsupported
+from zipwire._parser import find_eocd, parse_local_file_header
 from zipwire._zipinfo import RemoteZipInfo
 
 if typing.TYPE_CHECKING:
     from zipwire._types import AsyncReader, Writable
 
-_NOT_LOADED = "archive not loaded; use as an async context manager"
-
 
-class AsyncRemoteZip:
+class AsyncRemoteZip(RemoteZipBase):
     """Read files from a remote ZIP archive using async HTTP range requests.
 
     Must be used as an async context manager.  The archive is loaded on
@@ -35,27 +28,21 @@ class AsyncRemoteZip:
     Usage::
 
         async with AsyncRemoteZip(reader) as rz:
-            for info in await rz.infolist():
+            for info in rz.infolist():
                 print(info.filename)
             data = await rz.read("path/to/file.txt")
     """
 
     def __init__(self, reader: AsyncReader) -> None:
+        super().__init__()
         self._reader = reader
-        self._entries: list[RemoteZipInfo] | None = None
-        self._name_index: dict[str, RemoteZipInfo] | None = None
-        self._file_size: int | None = None
-        self._eocd: EOCDInfo | None = None
 
     async def __aenter__(self) -> AsyncRemoteZip:
         await self._ensure_loaded()
         return self
 
     async def __aexit__(self, *exc: object) -> None:
-        self._entries = None
-        self._name_index = None
-        self._file_size = None
-        self._eocd = None
+        self._clear()
         await self.close()
 
     async def close(self) -> None:
@@ -67,24 +54,16 @@ class AsyncRemoteZip:
         """The target URL of the underlying reader."""
         return self._reader.url
 
-    @property
-    def file_size(self) -> int:
-        """Total size of the remote archive in bytes."""
-        if self._file_size is None:
-            raise RuntimeError(_NOT_LOADED)
-        return self._file_size
+    async def _ensure_loaded(self) -> tuple[int, bytes]:
+        """Fetch and parse the central directory.
 
-    async def get_eocd_info(self) -> EOCDInfo:
-        """Return the parsed End of Central Directory record.
+        Returns:
+            ``(tail_start, tail_data)`` -- the offset and bytes of the
+            initial tail fetch.
 
-        Contains ``cd_offset``, ``cd_size``, and ``cd_entry_count``.
+        Raises:
+            RuntimeError: If called more than once.
         """
-        if self._eocd is None:
-            raise RuntimeError(_NOT_LOADED)
-        return self._eocd
-
-    async def _ensure_loaded(self) -> None:
-        """Fetch and parse the central directory."""
         if self._entries is not None:
             raise RuntimeError("_ensure_loaded() must not be called more than once")
 
@@ -96,46 +75,19 @@ class AsyncRemoteZip:
         cl = head_headers.get("content-length")
         if cl is None:
             raise RangeRequestUnsupported("Server did not return a Content-Length header")
-        self._file_size = int(cl)
-        tail_start = max(0, self._file_size - MAX_EOCD_SEARCH)
-        tail, _ = await self._reader.read_range(tail_start, self._file_size - tail_start)
+        file_size = int(cl)
+        fetch_size = min(file_size, self._tail_read_size(file_size))
+        tail_start = max(0, file_size - fetch_size)
+        tail, _ = await self._reader.read_range(tail_start, file_size - tail_start)
 
         # Step 2: Parse EOCD
-        eocd = find_eocd(tail, self._file_size)
-        self._eocd = eocd
+        eocd = find_eocd(tail, file_size)
 
-        # Step 3: Fetch and parse central directory
+        # Step 3: Fetch central directory and store parsed state
         cd_data, _ = await self._reader.read_range(eocd.cd_offset, eocd.cd_size)
-        raw_entries = parse_central_directory(cd_data, eocd.cd_entry_count)
-
-        # Step 4: Convert to RemoteZipInfo objects
-        self._entries = [RemoteZipInfo._from_central_dir_entry(e) for e in raw_entries]
-        self._name_index = {info.filename: info for info in self._entries}
+        self._set_entries(cd_data, file_size, eocd)
 
-    async def infolist(self) -> list[RemoteZipInfo]:
-        """Return a list of RemoteZipInfo objects for all files in the archive."""
-        if self._entries is None:
-            raise RuntimeError(_NOT_LOADED)
-        return list(self._entries)
-
-    async def namelist(self) -> list[str]:
-        """Return a list of filenames in the archive."""
-        if self._entries is None:
-            raise RuntimeError(_NOT_LOADED)
-        return [info.filename for info in self._entries]
-
-    async def getinfo(self, name: str) -> RemoteZipInfo:
-        """Return the RemoteZipInfo for the given filename.
-
-        Raises:
-            FileNotFoundInZip: If the name is not in the archive.
-        """
-        if self._name_index is None:
-            raise RuntimeError(_NOT_LOADED)
-        try:
-            return self._name_index[name]
-        except KeyError:
-            raise FileNotFoundInZip(name) from None
+        return tail_start, tail
 
     async def _resolve_entry(
         self,
@@ -149,10 +101,7 @@ class AsyncRemoteZip:
         compressed data are fetched in a single request and *prefetched*
         contains the compressed bytes.  Otherwise *prefetched* is ``None``.
         """
-        if isinstance(name, RemoteZipInfo):
-            info = name
-        else:
-            info = await self.getinfo(name)
+        info = name if isinstance(name, RemoteZipInfo) else self.getinfo(name)
         if info.is_dir():
             return None
 

zipwire-0.3.0/src/zipwire/_base.py

@@ -0,0 +1,97 @@
+"""Common base class for sync and async remote ZIP readers."""
+
+from __future__ import annotations
+
+from zipwire._constants import MAX_EOCD_SEARCH
+from zipwire._errors import FileNotFoundInZip
+from zipwire._parser import EOCDInfo, parse_central_directory
+from zipwire._zipinfo import RemoteZipInfo
+
+_NOT_LOADED = "archive not loaded; use as a context manager"
+
+
+class RemoteZipBase:
+    """Shared state and sync accessors for remote ZIP readers.
+
+    This class holds the parsed central directory entries, the name
+    index, file size, and EOCD record.  It is not meant to be
+    instantiated directly.
+    """
+
+    def __init__(self) -> None:
+        self._entries: list[RemoteZipInfo] | None = None
+        self._name_index: dict[str, RemoteZipInfo] | None = None
+        self._file_size: int | None = None
+        self._eocd: EOCDInfo | None = None
+
+    def _clear(self) -> None:
+        """Reset all loaded state."""
+        self._entries = None
+        self._name_index = None
+        self._file_size = None
+        self._eocd = None
+
+    def _set_entries(
+        self,
+        cd_data: bytes,
+        file_size: int,
+        eocd: EOCDInfo,
+    ) -> None:
+        """Parse central directory data and store entries."""
+        raw_entries = parse_central_directory(cd_data, eocd.cd_entry_count)
+        entries = [RemoteZipInfo._from_central_dir_entry(e) for e in raw_entries]
+        self._entries = entries
+        self._name_index = {info.filename: info for info in entries}
+        self._file_size = file_size
+        self._eocd = eocd
+
+    @property
+    def file_size(self) -> int:
+        """Total size of the remote archive in bytes."""
+        if self._file_size is None:
+            raise RuntimeError(_NOT_LOADED)
+        return self._file_size
+
+    @property
+    def eocd_info(self) -> EOCDInfo:
+        """Parsed End of Central Directory record.
+
+        Contains ``cd_offset``, ``cd_size``, and ``cd_entry_count``.
+        """
+        if self._eocd is None:
+            raise RuntimeError(_NOT_LOADED)
+        return self._eocd
+
+    def _tail_read_size(self, file_size: int) -> int:
+        """Return the number of bytes to fetch from the end of the file.
+
+        Called during loading to determine the tail size.
+        The default returns :data:`MAX_EOCD_SEARCH`.  Subclasses may
+        override this to request a larger tail.
+        """
+        return MAX_EOCD_SEARCH
+
+    def infolist(self) -> list[RemoteZipInfo]:
+        """Return a list of RemoteZipInfo objects for all files in the archive."""
+        if self._entries is None:
+            raise RuntimeError(_NOT_LOADED)
+        return list(self._entries)
+
+    def namelist(self) -> list[str]:
+        """Return a list of filenames in the archive."""
+        if self._entries is None:
+            raise RuntimeError(_NOT_LOADED)
+        return [info.filename for info in self._entries]
+
+    def getinfo(self, name: str) -> RemoteZipInfo:
+        """Return the RemoteZipInfo for the given filename.
+
+        Raises:
+            FileNotFoundInZip: If the name is not in the archive.
+        """
+        if self._name_index is None:
+            raise RuntimeError(_NOT_LOADED)
+        try:
+            return self._name_index[name]
+        except KeyError:
+            raise FileNotFoundInZip(name) from None

{zipwire-0.2.0 → zipwire-0.3.0}/src/zipwire/_sync.py

@@ -4,29 +4,22 @@ from __future__ import annotations
 
 import typing
 
+from zipwire._base import RemoteZipBase
 from zipwire._constants import (
     LOCAL_FILE_HEADER_SIZE,
-    MAX_EOCD_SEARCH,
     PREFETCH_EXTRA,
     PREFETCH_THRESHOLD,
 )
 from zipwire._decompress import StreamingDecompressor, decompress
-from zipwire._errors import FileNotFoundInZip, FileTooLarge, RangeRequestUnsupported
-from zipwire._parser import (
-    EOCDInfo,
-    find_eocd,
-    parse_central_directory,
-    parse_local_file_header,
-)
+from zipwire._errors import FileTooLarge, RangeRequestUnsupported
+from zipwire._parser import find_eocd, parse_local_file_header
 from zipwire._zipinfo import RemoteZipInfo
 
 if typing.TYPE_CHECKING:
     from zipwire._types import SyncReader, Writable
 
-_NOT_LOADED = "archive not loaded; use as a context manager"
-
 
-class SyncRemoteZip:
+class SyncRemoteZip(RemoteZipBase):
     """Read files from a remote ZIP archive using synchronous HTTP range requests.
 
     Must be used as a context manager.  The archive is loaded on entry
@@ -41,21 +34,15 @@ class SyncRemoteZip:
     """
 
     def __init__(self, reader: SyncReader) -> None:
+        super().__init__()
         self._reader = reader
-        self._entries: list[RemoteZipInfo] | None = None
-        self._name_index: dict[str, RemoteZipInfo] | None = None
-        self._file_size: int | None = None
-        self._eocd: EOCDInfo | None = None
 
     def __enter__(self) -> SyncRemoteZip:
         self._ensure_loaded()
         return self
 
     def __exit__(self, *exc: object) -> None:
-        self._entries = None
-        self._name_index = None
-        self._file_size = None
-        self._eocd = None
+        self._clear()
         self.close()
 
     def close(self) -> None:
@@ -67,25 +54,16 @@ class SyncRemoteZip:
         """The target URL of the underlying reader."""
         return self._reader.url
 
-    @property
-    def file_size(self) -> int:
-        """Total size of the remote archive in bytes."""
-        if self._file_size is None:
-            raise RuntimeError(_NOT_LOADED)
-        return self._file_size
+    def _ensure_loaded(self) -> tuple[int, bytes]:
+        """Fetch and parse the central directory.
 
-    @property
-    def eocd_info(self) -> EOCDInfo:
-        """Parsed End of Central Directory record.
+        Returns:
+            ``(tail_start, tail_data)`` -- the offset and bytes of the
+            initial tail fetch.
 
-        Contains ``cd_offset``, ``cd_size``, and ``cd_entry_count``.
+        Raises:
+            RuntimeError: If called more than once.
         """
-        if self._eocd is None:
-            raise RuntimeError(_NOT_LOADED)
-        return self._eocd
-
-    def _ensure_loaded(self) -> None:
-        """Fetch and parse the central directory."""
         if self._entries is not None:
             raise RuntimeError("_ensure_loaded() must not be called more than once")
 
@@ -97,46 +75,19 @@ class SyncRemoteZip:
         cl = head_headers.get("content-length")
         if cl is None:
             raise RangeRequestUnsupported("Server did not return a Content-Length header")
-        self._file_size = int(cl)
-        tail_start = max(0, self._file_size - MAX_EOCD_SEARCH)
-        tail, _ = self._reader.read_range(tail_start, self._file_size - tail_start)
+        file_size = int(cl)
+        fetch_size = min(file_size, self._tail_read_size(file_size))
+        tail_start = max(0, file_size - fetch_size)
+        tail, _ = self._reader.read_range(tail_start, file_size - tail_start)
 
         # Step 2: Parse EOCD
-        eocd = find_eocd(tail, self._file_size)
-        self._eocd = eocd
+        eocd = find_eocd(tail, file_size)
 
-        # Step 3: Fetch and parse central directory
+        # Step 3: Fetch central directory and store parsed state
         cd_data, _ = self._reader.read_range(eocd.cd_offset, eocd.cd_size)
-        raw_entries = parse_central_directory(cd_data, eocd.cd_entry_count)
+        self._set_entries(cd_data, file_size, eocd)
 
-        # Step 4: Convert to RemoteZipInfo objects
-        self._entries = [RemoteZipInfo._from_central_dir_entry(e) for e in raw_entries]
-        self._name_index = {info.filename: info for info in self._entries}
-
-    def infolist(self) -> list[RemoteZipInfo]:
-        """Return a list of RemoteZipInfo objects for all files in the archive."""
-        if self._entries is None:
-            raise RuntimeError(_NOT_LOADED)
-        return list(self._entries)
-
-    def namelist(self) -> list[str]:
-        """Return a list of filenames in the archive."""
-        if self._entries is None:
-            raise RuntimeError(_NOT_LOADED)
-        return [info.filename for info in self._entries]
-
-    def getinfo(self, name: str) -> RemoteZipInfo:
-        """Return the RemoteZipInfo for the given filename.
-
-        Raises:
-            FileNotFoundInZip: If the name is not in the archive.
-        """
-        if self._name_index is None:
-            raise RuntimeError(_NOT_LOADED)
-        try:
-            return self._name_index[name]
-        except KeyError:
-            raise FileNotFoundInZip(name) from None
+        return tail_start, tail
 
     def _resolve_entry(
         self,

{zipwire-0.2.0 → zipwire-0.3.0}/src/zipwire/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None