project-plan.md

project-plan.md — pinch

Goal

Port flutter_pinch to Python: a reusable library that retrieves a single file from inside a remote ZIP archive via HTTP Range requests, plus a CLI example that exercises it.

Milestones

• ZIP structure parsers (EOCD, Central Directory, Local File Header) — structures.py
• ZipEntry model + find_by_path — zip_entry.py
• Range HTTP helper with 206/200/416 handling — http.py
• Pinch service: fetch_directory() / fetch_file() — pinch.py
• CLI example (python -m pinch_example) — pinch_example/__main__.py
• Tests: parser unit tests + end-to-end over a local Range server
• Docs: README + Two-Tier CLAUDE.md + this plan
• (Future) ZIP64 support
• (Future) Encrypted-entry support
• (Future) Optional async API (httpx)

Decisions

• Stdlib only. HTTP via urllib, DEFLATE via zlib, parsing via struct. No runtime dependencies, for maximum portability. (User-confirmed.)
• Example is a CLI tool, mirroring the Flutter demo as a terminal app. (User-confirmed.)
• Docs: light memention setup — Two-Tier CLAUDE.md + project-plan.md, no cards/ directory. (User-confirmed.)
• src/ layout with two packages: pinch (library) and pinch_example (demo).
• Raw DEFLATE inflation uses wbits = -15 (no zlib header), matching the ZIP spec and the original implementation.

Current state

Complete and verified. pytest → 11 passing. CLI verified end-to-end against a real PyPI wheel (a ZIP served with Range support over HTTPS): lists all entries and extracts a single file transferring only the index + that file's bytes.

Open questions

• Which public hosts to recommend in docs? GitHub's /archive/*.zip endpoint streams without Content-Length, so it falls into the full-download fallback; PyPI wheel URLs (files.pythonhosted.org) support Range cleanly and make a good demo target.
• Worth adding a tiny in-repo fixture server script for offline demos?