Zipstream-NG

1.9.0 · active · verified Wed Apr 15

Zipstream-NG is a modern and easy-to-use Python library for generating streamable ZIP files on the fly. It allows packaging and streaming many files and folders without requiring temporary files or excessive memory, making it ideal for web backends. It also supports calculating the final ZIP file size before generation, enabling accurate Content-Length headers for HTTP responses. The current version is 1.9.0, and it maintains an active release cadence.

Warnings

gotcha Confusing Package Name vs. Import Path: The library is installed via `pip install zipstream-ng` but the primary class is imported as `from zipstream import ZipStream`. There is an older, unrelated `zipstream` package on PyPI which is no longer maintained. Ensure you are importing `ZipStream` from the correct module (`zipstream`) after installing `zipstream-ng`.
Fix: Always use `from zipstream import ZipStream` after installing `zipstream-ng`. Verify the correct package is installed with `pip show zipstream-ng`.
gotcha Potential for Corrupt Zips in Web Streaming: When streaming ZIPs over HTTP, incorrect handling of HTTP headers (e.g., `Content-Length`, `Content-Disposition`) or premature termination of the stream can lead to corrupt downloads. `zipstream-ng` can pre-calculate the size (if no compression is used), which is crucial for `Content-Length`.
Fix: For web applications, ensure you set `Content-Type: application/zip`, `Content-Disposition: attachment; filename="your_file.zip"`, and, if possible, `Content-Length` using `len(zs)` (where `zs` is your ZipStream instance without compression). Ensure the entire generator is consumed and sent to the client.
gotcha Encoding of String Data: When adding string data directly to the ZipStream (rather than files), ensure it's explicitly encoded to bytes (e.g., `my_string.encode('utf-8')`). Passing unencoded strings or incorrectly encoded bytes can lead to corrupted file contents within the ZIP archive.
Fix: Always encode string data to bytes before adding it to `ZipStream`. For example: `zs.add(my_string.encode('utf-8'), 'text_file.txt')`.

Install

pip install zipstream-ng Install stable version

Imports

ZipStream
wrong:
```
from zipstream_ng import ZipStream
```
correct:
```
from zipstream import ZipStream
```
The package is installed as 'zipstream-ng' but the main class 'ZipStream' is imported directly from the 'zipstream' module. Importing from 'zipstream_ng' will fail, and there's an older, separate library called 'zipstream' that is not `zipstream-ng` and may lead to unexpected behavior if imported by mistake.

Quickstart

This example demonstrates how to create a ZipStream from a local directory path and then iterate over its chunks to write the streamed ZIP content to a new file. This pattern is easily adaptable for streaming over an HTTP response or other byte sinks.

from zipstream import ZipStream
import os

# Create a dummy directory and files for the example
if not os.path.exists('my_files'):
    os.makedirs('my_files')
with open('my_files/file1.txt', 'w') as f:
    f.write('This is file one.')
with open('my_files/file2.txt', 'w') as f:
    f.write('This is file two.')

# Stream files from a directory into a zip file
output_filename = 'archive.zip'
zs = ZipStream.from_path('my_files')

# To save to a local file:
with open(output_filename, 'wb') as f:
    for chunk in zs:
        f.write(chunk)

print(f'Successfully created {output_filename} containing files from my_files/')

# Clean up dummy files
os.remove('my_files/file1.txt')
os.remove('my_files/file2.txt')
os.rmdir('my_files')

view raw JSON →