zipwire 0.0.1__tar.gz → 0.1.0__tar.gz

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

@@ -34,7 +34,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+    continue-on-error: ${{ matrix.python-version == '3.15' }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
@@ -43,7 +44,34 @@ jobs:
         with:
           enable-cache: true
       - run: uv sync --group dev --python ${{ matrix.python-version }}
-      - run: uv run pytest
+      - run: uv run coverage run -m pytest
+      - run: uv run pytest -m integration -v
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.*
+          include-hidden-files: true
+
+  coverage:
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
+        with:
+          enable-cache: true
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          pattern: coverage-*
+          merge-multiple: true
+      - run: uv tool install "coverage[toml]>=7.0"
+      - run: coverage combine
+      - run: coverage report
+      - run: coverage xml
 
   docs:
     runs-on: ubuntu-latest

zipwire-0.1.0/.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt
+   - method: pip
+     path: .
+     extra_requirements:
+       - all

zipwire-0.1.0/AGENTS.md

@@ -0,0 +1,53 @@
+# zipwire
+
+Read and extract files from remote ZIP archives over HTTP range requests.
+The library parses ZIP central directory and local file headers without
+downloading the entire archive, then streams and decompresses individual
+entries on the fly.
+
+## Source layout
+
+- `src/zipwire/` - main package (sync/async API, parsers, decompression)
+- `src/zipwire/backends/` - HTTP backend adapters (urllib3, httpx2, aiohttp, requests)
+- `tests/` - pytest test suite (async tests use `pytest-asyncio`)
+- `docs/` - Sphinx documentation (Furo theme, MyST markdown)
+
+## Virtual environment rules
+
+- **Always** use the `.venv` virtual environment in the project root.
+- Create it with `uv venv .venv` if it does not exist.
+- **Never** install packages into the system Python or any other environment.
+- Install the project: `uv pip install -e ".[all]" --python .venv/bin/python`
+- Install dev deps: `uv pip install "pytest>=8.0" "pytest-asyncio>=0.24" "pytest-httpserver>=1.1" "coverage[toml]>=7.0" --python .venv/bin/python`
+- Run tests directly: `.venv/bin/python -m pytest tests/`
+- Run any Python tool via `.venv/bin/python -m <tool>` or `.venv/bin/<tool>`.
+- Use `uv pip install --python .venv/bin/python` for all pip operations.
+
+## Code style rules
+
+- **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.
+
+## Git rules
+
+- **Always** sign off commits with `git commit -s`.
+  Every commit message must include a `Signed-off-by:` line.
+
+## Commands
+
+```bash
+# lint (ruff check + format)
+uvx --with tox-uv tox run -e lint
+
+# run tests (single Python version)
+uvx --with tox-uv tox run -e py314
+
+# run tests directly with .venv
+.venv/bin/python -m pytest tests/ -v
+
+# run full test matrix
+uvx --with tox-uv tox run -e py311,py312,py313,py314
+
+# build docs
+uvx --with tox-uv tox run -e docs
+```

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

@@ -1,14 +1,15 @@
 Metadata-Version: 2.4
 Name: zipwire
-Version: 0.0.1
+Version: 0.1.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/
 Project-URL: Source, https://github.com/tiran/zipwire
 Project-URL: Issues, https://github.com/tiran/zipwire/issues
 Author-email: Christian Heimes <christian@python.org>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
@@ -19,17 +20,17 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: urllib3>=2.0
+Requires-Dist: urllib3>=2
 Provides-Extra: aiohttp
 Requires-Dist: aiohttp>=3.9; extra == 'aiohttp'
 Provides-Extra: all
 Requires-Dist: aiohttp>=3.9; extra == 'all'
-Requires-Dist: httpx2>=2.0; extra == 'all'
-Requires-Dist: requests>=2.31; extra == 'all'
+Requires-Dist: httpx2[http2]>=2; extra == 'all'
+Requires-Dist: requests>=2.28; extra == 'all'
 Provides-Extra: httpx2
-Requires-Dist: httpx2>=2.0; extra == 'httpx2'
+Requires-Dist: httpx2[http2]>=2; extra == 'httpx2'
 Provides-Extra: requests
-Requires-Dist: requests>=2.31; extra == 'requests'
+Requires-Dist: requests>=2.28; extra == 'requests'
 Description-Content-Type: text/markdown
 
 # zipwire
@@ -72,13 +73,13 @@ sync and async:
 pip install zipwire[httpx2]
 ```
 
-| Backend  | Class              | Mode  | Install extra |
-|----------|--------------------|-------|---------------|
-| urllib3  | `Urllib3Reader`    | sync  | *(included)*  |
-| httpx2   | `Httpx2SyncReader` | sync  | `httpx2`      |
-| httpx2   | `Httpx2AsyncReader`| async | `httpx2`      |
-| requests | `RequestsReader`   | sync  | `requests`    |
-| aiohttp  | `AiohttpReader`    | async | `aiohttp`     |
+| Backend  | Class                | Mode  | HTTP    | Install extra |
+|----------|----------------------|-------|---------|---------------|
+| urllib3  | `Urllib3Reader`      | sync  | 1.1     | *(included)*  |
+| httpx2   | `Httpx2SyncReader`   | sync  | 1.1, 2  | `httpx2`      |
+| httpx2   | `Httpx2AsyncReader`  | async | 1.1, 2  | `httpx2`      |
+| requests | `RequestsReader`     | sync  | 1.1     | `requests`    |
+| aiohttp  | `AiohttpReader`      | async | 1.1     | `aiohttp`     |
 
 Every backend accepts an optional pre-configured client or session so you can
 share connection pools, authentication, and retry configuration.

{zipwire-0.0.1 → zipwire-0.1.0}/README.md

@@ -38,13 +38,13 @@ sync and async:
 pip install zipwire[httpx2]
 ```
 
-| Backend  | Class              | Mode  | Install extra |
-|----------|--------------------|-------|---------------|
-| urllib3  | `Urllib3Reader`    | sync  | *(included)*  |
-| httpx2   | `Httpx2SyncReader` | sync  | `httpx2`      |
-| httpx2   | `Httpx2AsyncReader`| async | `httpx2`      |
-| requests | `RequestsReader`   | sync  | `requests`    |
-| aiohttp  | `AiohttpReader`    | async | `aiohttp`     |
+| Backend  | Class                | Mode  | HTTP    | Install extra |
+|----------|----------------------|-------|---------|---------------|
+| urllib3  | `Urllib3Reader`      | sync  | 1.1     | *(included)*  |
+| httpx2   | `Httpx2SyncReader`   | sync  | 1.1, 2  | `httpx2`      |
+| httpx2   | `Httpx2AsyncReader`  | async | 1.1, 2  | `httpx2`      |
+| requests | `RequestsReader`     | sync  | 1.1     | `requests`    |
+| aiohttp  | `AiohttpReader`      | async | 1.1     | `aiohttp`     |
 
 Every backend accepts an optional pre-configured client or session so you can
 share connection pools, authentication, and retry configuration.

{zipwire-0.0.1 → zipwire-0.1.0}/docs/api.rst

@@ -15,16 +15,31 @@ Core
 .. autoclass:: zipwire.RemoteZipInfo
    :show-inheritance:
 
+Protocols and Types
+-------------------
+
+.. autoclass:: zipwire.SyncReader
+   :members:
+
+.. autoclass:: zipwire.AsyncReader
+   :members:
+
+.. autoclass:: zipwire.Headers
+   :members:
+
+.. autoclass:: zipwire.Writable
+   :members:
+
 Backends
 --------
 
 .. autoclass:: zipwire.backends._urllib3.Urllib3Reader
    :members:
 
-.. autoclass:: zipwire.backends._httpx2_sync.Httpx2SyncReader
+.. autoclass:: zipwire.backends._httpx2.Httpx2SyncReader
    :members:
 
-.. autoclass:: zipwire.backends._httpx2_async.Httpx2AsyncReader
+.. autoclass:: zipwire.backends._httpx2.Httpx2AsyncReader
    :members:
 
 .. autoclass:: zipwire.backends._requests.RequestsReader
@@ -43,6 +58,7 @@ Exceptions
        ├── BadZipFile
        ├── UnsupportedCompression
        ├── CRCMismatch
+       ├── FileTooLarge
        ├── RangeRequestUnsupported
        └── FileNotFoundInZip (also inherits KeyError)
 
@@ -58,6 +74,9 @@ Exceptions
 .. autoexception:: zipwire.CRCMismatch
    :show-inheritance:
 
+.. autoexception:: zipwire.FileTooLarge
+   :show-inheritance:
+
 .. autoexception:: zipwire.RangeRequestUnsupported
    :show-inheritance:
 

{zipwire-0.0.1 → zipwire-0.1.0}/docs/backends.rst

@@ -11,31 +11,37 @@ Available backends
 
 .. list-table::
    :header-rows: 1
-   :widths: 15 25 10 20
+   :widths: 15 25 10 10 20
 
    * - Library
      - Class
      - Mode
+     - HTTP
      - Install extra
    * - urllib3
      - :class:`~zipwire.backends.Urllib3Reader`
      - sync
+     - 1.1
      - *(included)*
    * - httpx2
      - :class:`~zipwire.backends.Httpx2SyncReader`
      - sync
+     - 1.1, 2
      - ``httpx2``
    * - httpx2
      - :class:`~zipwire.backends.Httpx2AsyncReader`
      - async
+     - 1.1, 2
      - ``httpx2``
    * - requests
      - :class:`~zipwire.backends.RequestsReader`
      - sync
+     - 1.1
      - ``requests``
    * - aiohttp
      - :class:`~zipwire.backends.AiohttpReader`
      - async
+     - 1.1
      - ``aiohttp``
 
 Choosing a backend
@@ -47,7 +53,10 @@ Choosing a backend
   Best choice if your project already depends on aiohttp.
 - **Sync + async from one library** - install ``httpx2`` and use
   :class:`~zipwire.backends.Httpx2SyncReader` or
-  :class:`~zipwire.backends.Httpx2AsyncReader`.
+  :class:`~zipwire.backends.Httpx2AsyncReader`.  The ``httpx2`` extra includes
+  HTTP/2 support via the ``h2`` package.  When ``h2`` is available, HTTP/2 is
+  enabled automatically; pass ``http2=False`` to force HTTP/1.1 or
+  ``http2=True`` to require it.
 - **Requests integration** - use :class:`~zipwire.backends.RequestsReader`
   if your project already uses ``requests`` and you want to share sessions,
   authentication, or retry configuration.
@@ -84,7 +93,7 @@ protocol and pass an instance to :class:`~zipwire.SyncRemoteZip` or
 
    from collections.abc import Iterator
 
-   from zipwire import SyncReader, SyncRemoteZip
+   from zipwire import Headers, SyncReader, SyncRemoteZip
 
 
    class MyReader:
@@ -93,11 +102,15 @@ protocol and pass an instance to :class:`~zipwire.SyncRemoteZip` or
        def __init__(self, url: str) -> None:
            self._url = url
 
-       def get_content_length(self) -> int:
-           ...  # HEAD request, return Content-Length
+       def head(self) -> Headers:
+           ...  # HEAD request, check Accept-Ranges, return headers
 
-       def read_range(self, offset: int, length: int) -> bytes:
-           ...  # GET with Range header
+       def read_range(
+           self,
+           offset: int,
+           length: int,
+       ) -> tuple[bytes, Headers]:
+           ...  # GET with Range header, return (data, response_headers)
 
        def stream_range(self, offset: int, length: int) -> Iterator[bytes]:
            ...  # GET with Range header, yield chunks
@@ -108,4 +121,52 @@ protocol and pass an instance to :class:`~zipwire.SyncRemoteZip` or
    assert isinstance(MyReader("..."), SyncReader)  # runtime-checkable
 
 See the :class:`~zipwire.SyncReader` and :class:`~zipwire.AsyncReader`
-protocol definitions in the source for the full method signatures.
+protocol definitions for the full method signatures.
+
+Why only absolute byte ranges?
+-------------------------------
+
+HTTP range requests support two forms: absolute ranges
+(``bytes=<start>-<end>``) and suffix ranges (``bytes=-<N>``).  Suffix
+ranges request the last *N* bytes without requiring the client to know
+the total file size.  While RFC 7233 defines both forms, support varies
+across CDNs and cloud storage services:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 40
+
+   * - Service
+     - Suffix ranges
+     - Notes
+   * - AWS S3
+     - supported
+     - Full RFC 7233 compliance.
+   * - Google Cloud Storage
+     - supported
+     - Confirmed by GCS team.
+   * - Azure Blob Storage
+     - **not supported**
+     - Returns 200 with full object instead of 206.
+   * - Amazon CloudFront
+     - **not supported**
+     - Returns 200 with full object instead of 206.
+   * - Cloudflare R2
+     - supported
+     - Via S3-compatible and Workers API.
+   * - Fastly
+     - varies
+     - Some Fastly-fronted origins (e.g. PyPI) return 501.
+   * - Cloudflare CDN
+     - uncertain
+     - Undocumented; may pass through to origin.
+   * - Akamai
+     - likely supported
+     - General range support confirmed; suffix ranges undocumented.
+
+Because suffix ranges silently break on several major platforms (returning
+the full object or an error), zipwire uses only absolute byte ranges.  On
+first access it sends a HEAD request to learn the file size, then
+computes absolute offsets for all subsequent range requests.  This adds
+one round-trip compared to a suffix-range approach but works reliably
+everywhere.

{zipwire-0.0.1 → zipwire-0.1.0}/docs/index.rst

@@ -7,6 +7,7 @@
 
    quickstart
    backends
+   security
 
 .. toctree::
    :maxdepth: 2

zipwire-0.1.0/docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx>=8.0
+furo>=2024.1
+sphinx-autobuild>=2024.1
+myst-parser>=4.0

zipwire-0.1.0/docs/security.rst

@@ -0,0 +1,96 @@
+Security
+========
+
+zipwire fetches data from remote servers and parses binary ZIP
+structures.  When processing archives from untrusted sources, keep the
+following risks in mind.
+
+Zip bombs
+---------
+
+A *zip bomb* is a malicious archive containing entries that decompress
+to a vastly larger size than their compressed representation, potentially
+exhausting memory or disk space.
+
+Both :meth:`~zipwire.SyncRemoteZip.read` and
+:meth:`~zipwire.SyncRemoteZip.read_into` (and their async equivalents)
+accept a ``max_file_size`` keyword argument that limits the uncompressed
+size of a single entry:
+
+.. code-block:: python
+
+   from zipwire import SyncRemoteZip
+   from zipwire.backends import Urllib3Reader
+
+   reader = Urllib3Reader("https://example.com/untrusted.zip")
+   with SyncRemoteZip(reader) as rz:
+       for info in rz.infolist():
+           data = rz.read(info, max_file_size=50 * 1024 * 1024)  # 50 MiB
+
+When the limit is exceeded, :exc:`~zipwire.FileTooLarge` is raised.
+
+**Two layers of protection:**
+
+1. **Pre-check** -- before decompression starts, the entry's declared
+   ``file_size`` from the central directory is compared against the limit.
+   This catches honest zip bombs with no overhead.
+
+2. **Streaming enforcement** (:meth:`read_into` only) -- the streaming
+   decompressor tracks the actual decompressed output and aborts if it
+   exceeds the limit.  This catches crafted archives that lie about their
+   uncompressed size in the metadata.
+
+:meth:`read` performs only the pre-check (layer 1).  Because it
+decompresses the entire entry into memory in one step, it cannot enforce
+the limit during decompression.  Use :meth:`read_into` when processing
+untrusted archives for defence in depth.
+
+You can also inspect entries before extracting them:
+
+.. code-block:: python
+
+   MAX_SIZE = 100 * 1024 * 1024  # 100 MiB
+
+   with SyncRemoteZip(reader) as rz:
+       for info in rz.infolist():
+           if info.file_size > MAX_SIZE:
+               print(f"Skipping {info.filename}: too large ({info.file_size} bytes)")
+               continue
+           data = rz.read(info)
+
+Path traversal
+--------------
+
+ZIP archives can contain entries with absolute paths or ``../``
+components (e.g. ``../../etc/passwd``).  zipwire does **not** extract
+files to disk, so this is not a direct risk.  However, if you use
+filenames from the archive to construct file paths, always sanitise them:
+
+.. code-block:: python
+
+   import os
+
+   with SyncRemoteZip(reader) as rz:
+       for info in rz.infolist():
+           # Reject absolute paths and path traversal
+           if os.path.isabs(info.filename) or ".." in info.filename.split("/"):
+               print(f"Skipping suspicious path: {info.filename}")
+               continue
+           dest = os.path.join(output_dir, info.filename)
+           # Verify the resolved path is inside output_dir
+           if not os.path.realpath(dest).startswith(os.path.realpath(output_dir)):
+               print(f"Skipping path traversal: {info.filename}")
+               continue
+
+Server trust
+------------
+
+zipwire sends HTTP requests to a URL you provide.  The server controls
+what data is returned.  A malicious server could return crafted responses
+designed to exploit ZIP parsing bugs, cause excessive memory use, or
+return different data for different range requests.
+
+- Only fetch archives from servers you trust.
+- Use HTTPS to prevent tampering in transit.
+- Consider setting ``max_file_size`` even for trusted servers as a
+  safety net.

{zipwire-0.0.1 → zipwire-0.1.0}/pyproject.toml

@@ -11,7 +11,7 @@ authors = [{ name = "Christian Heimes", email = "christian@python.org" }]
 requires-python = ">=3.11"
 readme = "README.md"
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
@@ -22,34 +22,35 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
     "Typing :: Typed",
 ]
-dependencies = ["urllib3>=2.0"]
+dependencies = ["urllib3>=2"]
 
 [project.urls]
 Homepage = "https://github.com/tiran/zipwire"
+Documentation = "https://zipwire.readthedocs.io/"
 Source = "https://github.com/tiran/zipwire"
 Issues = "https://github.com/tiran/zipwire/issues"
 
 [project.optional-dependencies]
-httpx2 = ["httpx2>=2.0"]
+httpx2 = ["httpx2[http2]>=2"]
 aiohttp = ["aiohttp>=3.9"]
-requests = ["requests>=2.31"]
-all = ["httpx2>=2.0", "aiohttp>=3.9", "requests>=2.31"]
+requests = ["requests>=2.28"]
+all = ["httpx2[http2]>=2", "aiohttp>=3.9", "requests>=2.28"]
 
 [dependency-groups]
 dev = [
     "zipwire[all]",
-    "pytest>=8.0",
+    "pytest>=8",
     "pytest-asyncio>=0.24",
-    "pytest-httpserver>=1.1",
-    "coverage[toml]>=7.0",
+    "pytest-httpserver>=1",
+    "coverage[toml]>=7",
     "ruff>=0.11",
 ]
 docs = [
     "zipwire[all]",
-    "sphinx>=8.0",
-    "furo>=2024.1",
-    "sphinx-autobuild>=2024.1",
-    "myst-parser>=4.0",
+    "sphinx>=8",
+    "furo>=2024",
+    "sphinx-autobuild>=2024",
+    "myst-parser>=4",
 ]
 
 [tool.hatch.version]
@@ -64,6 +65,8 @@ packages = ["src/zipwire"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
+markers = ["integration: tests that hit real network services (deselect with '-m not integration')"]
+addopts = "-m 'not integration'"
 
 [tool.ruff]
 line-length = 99
@@ -73,7 +76,16 @@ target-version = "py311"
 select = ["E", "W", "F", "I", "UP", "B", "SIM", "TCH", "RUF"]
 
 [tool.coverage.run]
+branch = true
+parallel = true
 source = ["zipwire"]
+omit = ["*/_version.py"]
+
+[tool.coverage.paths]
+source = [
+    "src/zipwire",
+    ".tox/*/lib/python*/site-packages/zipwire",
+]
 
 [tool.coverage.report]
 show_missing = true

{zipwire-0.0.1 → zipwire-0.1.0}/src/zipwire/__init__.py

@@ -8,12 +8,13 @@ from zipwire._errors import (
     BadZipFile,
     CRCMismatch,
     FileNotFoundInZip,
+    FileTooLarge,
     RangeRequestUnsupported,
     UnsupportedCompression,
     ZipwireError,
 )
 from zipwire._sync import SyncRemoteZip
-from zipwire._types import AsyncReader, SyncReader, Writable
+from zipwire._types import AsyncReader, Headers, SyncReader, Writable
 from zipwire._zipinfo import RemoteZipInfo
 
 __all__ = [
@@ -23,6 +24,8 @@ __all__ = [
     "CRCMismatch",
     "CompressionMethod",
     "FileNotFoundInZip",
+    "FileTooLarge",
+    "Headers",
     "RangeRequestUnsupported",
     "RemoteZipInfo",
     "SyncReader",