zipwire 0.1.0__tar.gz → 0.2.0__tar.gz

{zipwire-0.1.0 → zipwire-0.2.0}/.github/workflows/ci.yml

@@ -43,10 +43,10 @@ jobs:
       - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
         with:
           enable-cache: true
-      - run: uv sync --group dev --python ${{ matrix.python-version }}
-      - run: uv run coverage run -m pytest
-      - run: uv run pytest -m integration -v
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
+      - run: uv tool install --python ${{ matrix.python-version }} tox --with tox-uv --with tox-gh
+      - run: tox
+      - run: tox -e integration
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: coverage-${{ matrix.python-version }}
           path: .coverage.*
@@ -64,7 +64,7 @@ jobs:
       - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
         with:
           enable-cache: true
-      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
         with:
           pattern: coverage-*
           merge-multiple: true

{zipwire-0.1.0 → zipwire-0.2.0}/.github/workflows/codeql.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
-      - uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9  # v4.37.0
+      - uses: github/codeql-action/init@7188fc363630916deb702c7fdcf4e481b751f97a  # v4.37.1
         with:
           languages: python
-      - uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9  # v4.37.0
+      - uses: github/codeql-action/analyze@7188fc363630916deb702c7fdcf4e481b751f97a  # v4.37.1

{zipwire-0.1.0 → zipwire-0.2.0}/.github/workflows/scorecard.yml

@@ -28,6 +28,6 @@ jobs:
           name: scorecard-results
           path: results.sarif
           retention-days: 5
-      - uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9  # v4.37.0
+      - uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a  # v4.37.1
         with:
           sarif_file: results.sarif

{zipwire-0.1.0 → zipwire-0.2.0}/AGENTS.md

@@ -28,6 +28,18 @@ entries on the fly.
 - **No local imports.** All imports must be at the top of the file.
   Do not use `from foo import bar` inside functions, methods, or test bodies.
 
+## Documentation rules
+
+- **Keep docs in sync with API changes.** Whenever you add, remove, rename,
+  or change the signature of any public API (classes, functions, exceptions,
+  type aliases, backends), you **must** update all of these:
+  1. `src/zipwire/__init__.py` -- module docstring (usage examples, backend
+     list) and `__all__`.
+  2. `docs/` -- Sphinx sources (`api.rst`, `backends.rst`, `quickstart.rst`,
+     and any other affected `.rst` file).
+- After editing docs, verify they build cleanly:
+  `uvx --with tox-uv tox run -e docs`
+
 ## Git rules
 
 - **Always** sign off commits with `git commit -s`.

zipwire-0.2.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zipwire
-Version: 0.1.0
+Version: 0.2.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.1.0 → zipwire-0.2.0}/docs/api.rst

@@ -4,6 +4,18 @@ API Reference
 Core
 ----
 
+.. note::
+
+   ``SyncRemoteZip`` and ``AsyncRemoteZip`` **must** be used as context
+   managers.  The archive is loaded on entry and all internal state is
+   cleared on exit.  Calling methods like :meth:`~zipwire.SyncRemoteZip.read`
+   outside a ``with`` / ``async with`` block raises :exc:`RuntimeError`.
+
+.. warning::
+
+   ``SyncRemoteZip`` and ``AsyncRemoteZip`` instances are **not thread-safe**.
+   Each thread or task should use its own instance.
+
 .. autoclass:: zipwire.SyncRemoteZip
    :members:
    :special-members: __enter__, __exit__
@@ -15,6 +27,9 @@ Core
 .. autoclass:: zipwire.RemoteZipInfo
    :show-inheritance:
 
+.. autoclass:: zipwire.EOCDInfo
+   :members:
+
 Protocols and Types
 -------------------
 

zipwire-0.2.0/src/zipwire/__init__.py

@@ -0,0 +1,98 @@
+"""Read and extract files from remote ZIP archives over HTTP range requests.
+
+Only the central directory and the requested entries are downloaded,
+so large archives can be inspected and partially extracted without
+fetching the entire file.
+
+Synchronous example
+-------------------
+
+::
+
+    from zipwire import SyncRemoteZip
+    from zipwire.backends import Urllib3Reader
+
+    reader = Urllib3Reader("https://example.com/archive.zip")
+    with SyncRemoteZip(reader) as rz:
+        for info in rz.infolist():
+            print(f"{info.filename}  {info.file_size} bytes")
+        data = rz.read("path/inside/archive.txt")
+
+        # Stream a large entry directly to disk
+        with open("local.bin", "wb") as fh:
+            rz.read_into("large-file.bin", fh)
+
+Asynchronous example
+--------------------
+
+::
+
+    import asyncio
+    from zipwire import AsyncRemoteZip
+    from zipwire.backends import AiohttpReader
+
+    async def main():
+        reader = AiohttpReader("https://example.com/archive.zip")
+        async with AsyncRemoteZip(reader) as rz:
+            print(await rz.namelist())
+            data = await rz.read("path/inside/archive.txt")
+
+            # Stream a large entry directly to disk
+            with open("local.bin", "wb") as fh:
+                await rz.read_into("large-file.bin", fh)
+
+    asyncio.run(main())
+
+Backends
+--------
+
+All backends live in :mod:`zipwire.backends` and are lazily imported.
+
+Synchronous:
+  - ``Urllib3Reader`` -- default, uses *urllib3*
+  - ``RequestsReader`` -- uses *requests* (``pip install zipwire[requests]``)
+  - ``Httpx2SyncReader`` -- uses *httpx2*, supports HTTP/2
+    (``pip install zipwire[httpx2]``)
+
+Asynchronous:
+  - ``AiohttpReader`` -- uses *aiohttp* (``pip install zipwire[aiohttp]``)
+  - ``Httpx2AsyncReader`` -- uses *httpx2*, supports HTTP/2
+    (``pip install zipwire[httpx2]``)
+"""
+
+from __future__ import annotations
+
+from zipwire._async import AsyncRemoteZip
+from zipwire._constants import CompressionMethod
+from zipwire._errors import (
+    BadZipFile,
+    CRCMismatch,
+    FileNotFoundInZip,
+    FileTooLarge,
+    RangeRequestUnsupported,
+    UnsupportedCompression,
+    ZipwireError,
+)
+from zipwire._parser import EOCDInfo
+from zipwire._sync import SyncRemoteZip
+from zipwire._types import AsyncReader, Headers, SyncReader, Writable
+from zipwire._zipinfo import RemoteZipInfo
+
+__all__ = [
+    "AsyncReader",
+    "AsyncRemoteZip",
+    "BadZipFile",
+    "CRCMismatch",
+    "CompressionMethod",
+    "EOCDInfo",
+    "FileNotFoundInZip",
+    "FileTooLarge",
+    "Headers",
+    "RangeRequestUnsupported",
+    "RemoteZipInfo",
+    "SyncReader",
+    "SyncRemoteZip",
+    "UnsupportedCompression",
+    "Writable",
+    "ZipwireError",
+]

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

@@ -29,10 +29,8 @@ def _print_table(infos: list[RemoteZipInfo], skip_dirs: bool) -> None:
 def _run_sync(url: str, backend: str, skip_dirs: bool) -> None:
     from zipwire import backends
 
-    reader_cls = {
-        "urllib3": backends.Urllib3Reader,
-        "requests": backends.RequestsReader,
-    }[backend]
+    names = {"urllib3": "Urllib3Reader", "requests": "RequestsReader"}
+    reader_cls = getattr(backends, names[backend])
     with SyncRemoteZip(reader_cls(url)) as rz:
         _print_table(rz.infolist(), skip_dirs)
 
@@ -40,10 +38,8 @@ def _run_sync(url: str, backend: str, skip_dirs: bool) -> None:
 async def _run_async(url: str, backend: str, skip_dirs: bool) -> None:
     from zipwire import backends
 
-    reader_cls = {
-        "httpx2": backends.Httpx2AsyncReader,
-        "aiohttp": backends.AiohttpReader,
-    }[backend]
+    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)
 

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

@@ -13,6 +13,7 @@ from zipwire._constants import (
 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,
@@ -22,10 +23,15 @@ 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:
     """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
+    entry and all internal state is cleared on exit.  Not thread-safe.
+
     Usage::
 
         async with AsyncRemoteZip(reader) as rz:
@@ -39,21 +45,48 @@ class AsyncRemoteZip:
         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
         await self.close()
 
     async def close(self) -> None:
         """Close the underlying reader."""
         await self._reader.close()
 
+    @property
+    def url(self) -> str:
+        """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 get_eocd_info(self) -> EOCDInfo:
+        """Return the 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
+
     async def _ensure_loaded(self) -> None:
-        """Fetch and parse the central directory if not already done."""
+        """Fetch and parse the central directory."""
         if self._entries is not None:
-            return
+            raise RuntimeError("_ensure_loaded() must not be called more than once")
 
         # Step 1: HEAD to get total size, then fetch the tail for EOCD search.
         # We use HEAD + absolute range instead of a single suffix-range
@@ -69,6 +102,7 @@ class AsyncRemoteZip:
 
         # Step 2: Parse EOCD
         eocd = find_eocd(tail, self._file_size)
+        self._eocd = eocd
 
         # Step 3: Fetch and parse central directory
         cd_data, _ = await self._reader.read_range(eocd.cd_offset, eocd.cd_size)
@@ -80,14 +114,14 @@ class AsyncRemoteZip:
 
     async def infolist(self) -> list[RemoteZipInfo]:
         """Return a list of RemoteZipInfo objects for all files in the archive."""
-        await self._ensure_loaded()
-        assert self._entries is not None
+        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."""
-        await self._ensure_loaded()
-        assert self._entries is not None
+        if self._entries is None:
+            raise RuntimeError(_NOT_LOADED)
         return [info.filename for info in self._entries]
 
     async def getinfo(self, name: str) -> RemoteZipInfo:
@@ -96,8 +130,8 @@ class AsyncRemoteZip:
         Raises:
             FileNotFoundInZip: If the name is not in the archive.
         """
-        await self._ensure_loaded()
-        assert self._name_index is not None
+        if self._name_index is None:
+            raise RuntimeError(_NOT_LOADED)
         try:
             return self._name_index[name]
         except KeyError:

{zipwire-0.1.0 → zipwire-0.2.0}/src/zipwire/_decompress.py

@@ -64,11 +64,11 @@ def decompress(
             result = lzma.decompress(data)
         case CompressionMethod.ZSTANDARD:
             try:
-                import zstandard  # ty: ignore[unresolved-import]
+                from compression.zstd import decompress as _zstd_decompress
             except ImportError:  # pragma: no cover
                 raise UnsupportedCompression(method) from None
 
-            result = zstandard.ZstdDecompressor().decompress(data, max_output_size=expected_size)
+            result = _zstd_decompress(data)
         case _:
             raise UnsupportedCompression(method)
 
@@ -128,12 +128,12 @@ class StreamingDecompressor:
                 self._dobj = lzma.LZMADecompressor()
             case CompressionMethod.ZSTANDARD:
                 try:
-                    import zstandard  # ty: ignore[unresolved-import]
+                    from compression.zstd import ZstdDecompressor
                 except ImportError:  # pragma: no cover
                     raise UnsupportedCompression(method) from None
 
                 self._mode = _DecompressMode.INCREMENTAL
-                self._dobj = zstandard.ZstdDecompressor().decompressobj()
+                self._dobj = ZstdDecompressor()
             case _:
                 raise UnsupportedCompression(method)
 

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

@@ -13,6 +13,7 @@ from zipwire._constants import (
 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,
@@ -22,10 +23,15 @@ 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:
     """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
+    and all internal state is cleared on exit.  Not thread-safe.
+
     Usage::
 
         with SyncRemoteZip(reader) as rz:
@@ -39,21 +45,49 @@ class SyncRemoteZip:
         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.close()
 
     def close(self) -> None:
         """Close the underlying reader."""
         self._reader.close()
 
+    @property
+    def url(self) -> str:
+        """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
+
+    @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 _ensure_loaded(self) -> None:
-        """Fetch and parse the central directory if not already done."""
+        """Fetch and parse the central directory."""
         if self._entries is not None:
-            return
+            raise RuntimeError("_ensure_loaded() must not be called more than once")
 
         # Step 1: HEAD to get total size, then fetch the tail for EOCD search.
         # We use HEAD + absolute range instead of a single suffix-range
@@ -69,6 +103,7 @@ class SyncRemoteZip:
 
         # Step 2: Parse EOCD
         eocd = find_eocd(tail, self._file_size)
+        self._eocd = eocd
 
         # Step 3: Fetch and parse central directory
         cd_data, _ = self._reader.read_range(eocd.cd_offset, eocd.cd_size)
@@ -80,14 +115,14 @@ class SyncRemoteZip:
 
     def infolist(self) -> list[RemoteZipInfo]:
         """Return a list of RemoteZipInfo objects for all files in the archive."""
-        self._ensure_loaded()
-        assert self._entries is not None
+        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."""
-        self._ensure_loaded()
-        assert self._entries is not None
+        if self._entries is None:
+            raise RuntimeError(_NOT_LOADED)
         return [info.filename for info in self._entries]
 
     def getinfo(self, name: str) -> RemoteZipInfo:
@@ -96,8 +131,8 @@ class SyncRemoteZip:
         Raises:
             FileNotFoundInZip: If the name is not in the archive.
         """
-        self._ensure_loaded()
-        assert self._name_index is not None
+        if self._name_index is None:
+            raise RuntimeError(_NOT_LOADED)
         try:
             return self._name_index[name]
         except KeyError:

{zipwire-0.1.0 → zipwire-0.2.0}/src/zipwire/_types.py

@@ -32,6 +32,11 @@ class Headers(typing.Protocol):
 class SyncReader(typing.Protocol):
     """Protocol for synchronous HTTP range-request readers."""
 
+    @property
+    def url(self) -> str:
+        """The target URL for this reader."""
+        ...
+
     def read_range(
         self,
         offset: int,
@@ -67,6 +72,11 @@ class SyncReader(typing.Protocol):
 class AsyncReader(typing.Protocol):
     """Protocol for asynchronous HTTP range-request readers."""
 
+    @property
+    def url(self) -> str:
+        """The target URL for this reader."""
+        ...
+
     async def read_range(
         self,
         offset: int,

{zipwire-0.1.0 → zipwire-0.2.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.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

{zipwire-0.1.0 → zipwire-0.2.0}/src/zipwire/backends/_aiohttp.py

@@ -7,7 +7,7 @@ import typing
 
 try:
     import aiohttp
-except ImportError as exc:  # pragma: no cover
+except ImportError as exc:
     raise ImportError(
         "AiohttpReader requires aiohttp. Install it with: pip install zipwire[aiohttp]"
     ) from exc
@@ -38,6 +38,11 @@ class AiohttpReader:
         self._session = session or aiohttp.ClientSession()
         self._allow_redirects = allow_redirects
 
+    @property
+    def url(self) -> str:
+        """The target URL for this reader."""
+        return self._url
+
     async def head(self) -> Headers:
         logger.debug("HEAD %s", self._url)
         async with self._session.head(self._url, allow_redirects=self._allow_redirects) as resp:

{zipwire-0.1.0 → zipwire-0.2.0}/src/zipwire/backends/_httpx2.py

@@ -7,7 +7,7 @@ import typing
 
 try:
     import httpx2
-except ImportError as exc:  # pragma: no cover
+except ImportError as exc:
     raise ImportError(
         "httpx2 readers require httpx2. Install it with: pip install zipwire[httpx2]"
     ) from exc
@@ -46,10 +46,15 @@ class Httpx2SyncReader:
         if client is not None:
             self._client = client
         else:
-            if http2 is None:
+            if http2 is None:  # pragma: no cover
                 http2 = _h2_available
             self._client = httpx2.Client(http2=http2, follow_redirects=allow_redirects)
 
+    @property
+    def url(self) -> str:
+        """The target URL for this reader."""
+        return self._url
+
     def head(self) -> Headers:
         logger.debug("HEAD %s", self._url)
         resp = self._client.head(self._url)
@@ -109,10 +114,15 @@ class Httpx2AsyncReader:
         if client is not None:
             self._client = client
         else:
-            if http2 is None:
+            if http2 is None:  # pragma: no cover
                 http2 = _h2_available
             self._client = httpx2.AsyncClient(http2=http2, follow_redirects=allow_redirects)
 
+    @property
+    def url(self) -> str:
+        """The target URL for this reader."""
+        return self._url
+
     async def head(self) -> Headers:
         logger.debug("HEAD %s", self._url)
         resp = await self._client.head(self._url)

{zipwire-0.1.0 → zipwire-0.2.0}/src/zipwire/backends/_requests.py

@@ -7,7 +7,7 @@ import typing
 
 try:
     import requests
-except ImportError as exc:  # pragma: no cover
+except ImportError as exc:
     raise ImportError(
         "RequestsReader requires requests. Install it with: pip install zipwire[requests]"
     ) from exc
@@ -38,6 +38,11 @@ class RequestsReader:
         self._session = session or requests.Session()
         self._allow_redirects = allow_redirects
 
+    @property
+    def url(self) -> str:
+        """The target URL for this reader."""
+        return self._url
+
     def head(self) -> Headers:
         logger.debug("HEAD %s", self._url)
         resp = self._session.head(self._url, allow_redirects=self._allow_redirects)

{zipwire-0.1.0 → zipwire-0.2.0}/src/zipwire/backends/_urllib3.py

@@ -33,6 +33,11 @@ class Urllib3Reader:
         self._pool = pool or urllib3.PoolManager()
         self._allow_redirects = allow_redirects
 
+    @property
+    def url(self) -> str:
+        """The target URL for this reader."""
+        return self._url
+
     def head(self) -> Headers:
         logger.debug("HEAD %s", self._url)
         resp = self._pool.request("HEAD", self._url, redirect=self._allow_redirects)