API Reference¶

Core¶

class zipwire.SyncRemoteZip(reader)[source]¶

Read files from a remote ZIP archive using synchronous HTTP range requests.

Usage:

with SyncRemoteZip(reader) as rz:
    for info in rz.infolist():
        print(info.filename)
    data = rz.read("path/to/file.txt")

Parameters:: reader (SyncReader)

close()[source]¶

Close the underlying reader.

Return type:: None

infolist()[source]¶

Return a list of RemoteZipInfo objects for all files in the archive.

Return type:: list[RemoteZipInfo]

namelist()[source]¶

Return a list of filenames in the archive.

Return type:: list[str]

getinfo(name)[source]¶

Return the RemoteZipInfo for the given filename.

Raises:: FileNotFoundInZip – If the name is not in the archive.
Parameters:: name (str)
Return type:: RemoteZipInfo

read(name, *, max_file_size=None)[source]¶

Read and decompress a file from the archive.

Parameters:

name (str | RemoteZipInfo) – Filename string or RemoteZipInfo object.
max_file_size (int | None) – Optional limit on uncompressed size in bytes. Raises FileTooLarge if the entry’s file_size exceeds this limit.

Returns:

The decompressed file contents.

Return type:

bytes

Warning

This method loads the entire decompressed file into memory. It checks the entry’s declared file_size against max_file_size, but a crafted archive may lie about its uncompressed size. Use read_into() for defence in depth: it enforces the size limit during decompression.

read_into(name, dest, *, max_file_size=None)[source]¶

Decompress a file from the archive into a writable destination.

Unlike read(), this truly streams: the compressed payload is fetched in chunks via stream_range() and each chunk is decompressed and written immediately, keeping peak memory low.

The streaming decompressor also enforces max_file_size during decompression, aborting if the actual output exceeds the limit regardless of what the entry metadata claims.

Parameters:

name (str | RemoteZipInfo) – Filename string or RemoteZipInfo object.
dest (Writable) – A writable file-like object (e.g. io.BytesIO, open file).
max_file_size (int | None) – Optional limit on uncompressed size in bytes. Raises FileTooLarge if the entry’s file_size exceeds this limit, or if the actual decompressed output exceeds it.

Return type:

None

class zipwire.AsyncRemoteZip(reader)[source]¶

Read files from a remote ZIP archive using async HTTP range requests.

Usage:

async with AsyncRemoteZip(reader) as rz:
    for info in await rz.infolist():
        print(info.filename)
    data = await rz.read("path/to/file.txt")

Parameters:: reader (AsyncReader)

async close()[source]¶

Close the underlying reader.

Return type:: None

async infolist()[source]¶

Return a list of RemoteZipInfo objects for all files in the archive.

Return type:: list[RemoteZipInfo]

async namelist()[source]¶

Return a list of filenames in the archive.

Return type:: list[str]

async getinfo(name)[source]¶

Return the RemoteZipInfo for the given filename.

Raises:: FileNotFoundInZip – If the name is not in the archive.
Parameters:: name (str)
Return type:: RemoteZipInfo

async read(name, *, max_file_size=None)[source]¶

Read and decompress a file from the archive.

Parameters:

name (str | RemoteZipInfo) – Filename string or RemoteZipInfo object.
max_file_size (int | None) – Optional limit on uncompressed size in bytes. Raises FileTooLarge if the entry’s file_size exceeds this limit.

Returns:

The decompressed file contents.

Return type:

bytes

Warning

async read_into(name, dest, *, max_file_size=None)[source]¶

Decompress a file from the archive into a writable destination.

Unlike read(), this truly streams: the compressed payload is fetched in chunks via stream_range() and each chunk is decompressed and written immediately, keeping peak memory low.

The streaming decompressor also enforces max_file_size during decompression, aborting if the actual output exceeds the limit regardless of what the entry metadata claims.

Parameters:

name (str | RemoteZipInfo) – Filename string or RemoteZipInfo object.
dest (Writable) – A writable file-like object (e.g. io.BytesIO, open file).
max_file_size (int | None) – Optional limit on uncompressed size in bytes. Raises FileTooLarge if the entry’s file_size exceeds this limit, or if the actual decompressed output exceeds it.

Return type:

None

class zipwire.RemoteZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))[source]¶

Bases: ZipInfo

A ZipInfo subclass for entries from a remote ZIP archive.

isinstance(info, zipfile.ZipInfo) returns True. All standard attributes and methods (is_dir, FileHeader, etc.) are available.

Protocols and Types¶

class zipwire.SyncReader(*args, **kwargs)[source]¶

Protocol for synchronous HTTP range-request readers.

read_range(offset, length)[source]¶

Read length bytes starting at absolute byte position offset.

Sends Range: bytes=<offset>-<offset+length-1>.

Returns the response body and the HTTP response headers.

Parameters:

offset (int)
length (int)

Return type:

tuple[bytes, Headers]

head()[source]¶

Send a HEAD request and return the response headers.

Raises:: RangeRequestUnsupported – If the server does not advertise Accept-Ranges: bytes.
Return type:: Headers

stream_range(offset, length)[source]¶

Stream length bytes starting at offset as chunks.

Parameters:

offset (int)
length (int)

Return type:

Iterator[bytes]

close()[source]¶

Release any held resources.

Return type:: None

class zipwire.AsyncReader(*args, **kwargs)[source]¶

Protocol for asynchronous HTTP range-request readers.

async read_range(offset, length)[source]¶

Read length bytes starting at absolute byte position offset.

Sends Range: bytes=<offset>-<offset+length-1>.

Returns the response body and the HTTP response headers.

Parameters:

offset (int)
length (int)

Return type:

tuple[bytes, Headers]

async head()[source]¶

Send a HEAD request and return the response headers.

Raises:: RangeRequestUnsupported – If the server does not advertise Accept-Ranges: bytes.
Return type:: Headers

stream_range(offset, length)[source]¶

Stream length bytes starting at offset as chunks.

Parameters:

offset (int)
length (int)

Return type:

AsyncIterator[bytes]

async close()[source]¶

Release any held resources.

Return type:: None

class zipwire.Headers(*args, **kwargs)[source]¶

HTTP response headers returned by head() and read_range().

Implementations must support case-insensitive lookup or use lower-case keys so that headers["content-length"] always works.

All standard HTTP header mapping types satisfy this protocol, including urllib3.HTTPHeaderDict, requests.structures.CaseInsensitiveDict, httpx2.Headers, aiohttp.CIMultiDictProxy, and plain dict with lower-case keys.

class zipwire.Writable(*args, **kwargs)[source]¶: Protocol for writable file-like objects (io.BytesIO, io.BufferedWriter, etc.).

Backends¶

class zipwire.backends._urllib3.Urllib3Reader(url, *, pool=None, allow_redirects=True)[source]¶

SyncReader implementation using urllib3.PoolManager.

Parameters:

url (str)
pool (urllib3.PoolManager | None)
allow_redirects (bool)

class zipwire.backends._httpx2.Httpx2SyncReader(url, *, client=None, http2=None, allow_redirects=True)[source]¶

SyncReader implementation using httpx2.Client.

Parameters:

url (str)
client (httpx2.Client | None)
http2 (bool | None)
allow_redirects (bool)

class zipwire.backends._httpx2.Httpx2AsyncReader(url, *, client=None, http2=None, allow_redirects=True)[source]¶

AsyncReader implementation using httpx2.AsyncClient.

Parameters:

url (str)
client (httpx2.AsyncClient | None)
http2 (bool | None)
allow_redirects (bool)

class zipwire.backends._requests.RequestsReader(url, *, session=None, allow_redirects=True)[source]¶

SyncReader implementation using requests.Session.

Parameters:

url (str)
session (requests.Session | None)
allow_redirects (bool)

class zipwire.backends._aiohttp.AiohttpReader(url, *, session=None, allow_redirects=True)[source]¶

AsyncReader implementation using aiohttp.ClientSession.

Parameters:

url (str)
session (aiohttp.ClientSession | None)
allow_redirects (bool)

Exceptions¶

Exception
└── ZipwireError
    ├── BadZipFile
    ├── UnsupportedCompression
    ├── CRCMismatch
    ├── FileTooLarge
    ├── RangeRequestUnsupported
    └── FileNotFoundInZip (also inherits KeyError)

exception zipwire.ZipwireError[source]¶

Bases: Exception

Base exception for all zipwire errors.

exception zipwire.BadZipFile[source]¶

Bases: ZipwireError

The data does not appear to be a valid ZIP archive.

exception zipwire.UnsupportedCompression(method)[source]¶

Bases: ZipwireError

The file uses an unsupported compression method.

Parameters:: method (int)
Return type:: None

exception zipwire.CRCMismatch(expected, actual)[source]¶

Bases: ZipwireError

CRC-32 check failed after decompression.

Parameters:

expected (int)
actual (int)

Return type:

None

exception zipwire.FileTooLarge(filename, file_size, max_size)[source]¶

Bases: ZipwireError

The entry’s uncompressed size exceeds the configured limit.

Parameters:

filename (str)
file_size (int)
max_size (int)

Return type:

None

exception zipwire.RangeRequestUnsupported[source]¶

Bases: ZipwireError

The HTTP server does not support range requests.

exception zipwire.FileNotFoundInZip(filename)[source]¶

Bases: ZipwireError, KeyError

The requested file was not found in the ZIP archive.

Parameters:: filename (str)
Return type:: None