CLAUDE.md

CLAUDE.md — pinch

Slim, always-loaded overview. For the full algorithm, byte offsets, and module contract, read docs/CLAUDE.full.md. For goals and status, read project-plan.md.

What this is

pinch retrieves a single file from inside a remote ZIP archive using HTTP Range requests — without downloading the whole archive. A Python port of flutter_pinch. Zero runtime dependencies (stdlib urllib + zlib + struct).

Layout

• src/pinch/ — the library
  • structures.py — ZIP binary parsers (EOCD, Central Directory, Local File Header)
  • zip_entry.py — ZipEntry dataclass + find_by_path
  • http.py — Range GET/HEAD helper over urllib; defines PinchError
  • pinch.py — Pinch service: fetch_directory(), fetch_file()
• src/pinch_example/__main__.py — CLI demo (python -m pinch_example)
• tests/ — pytest, ZIPs built with stdlib zipfile, served over a local HTTP server

Public API

from pinch import Pinch, ZipEntry, PinchError, find_by_path

pinch = Pinch()
entries = pinch.fetch_directory(url)        # list[ZipEntry], directories filtered out
entry   = find_by_path(entries, "a/b.txt")
result  = pinch.fetch_file(entry)           # ZipEntry with .data set (bytes)
pinch.bytes_transferred                     # int, for demonstrating savings

Run

pip install -e ".[test]"
pytest
python -m pinch_example <zip-url> [path-in-zip] [-o out]

Conventions

• Stdlib only — do not add runtime dependencies.
• All ZIP integers are little-endian (struct format strings start with <).
• Network/format failures surface as PinchError.