aiogzip 1.3.2

Asynchronous gzip file reader/writer with aiocsv support.

aiogzip ⚡️

An asynchronous library for reading and writing gzip-compressed files.

aiogzip provides a fast, simple, and asyncio-native interface for handling .gz files, making it a useful complement to Python's built-in gzip module for asynchronous applications.

🚀 Read the Documentation

Features

• Truly Asynchronous: Built with asyncio and aiofiles.
• High-Performance: Optimized buffer handling for fast I/O.
• Drop-in Replacement: Mimics gzip.open() with async seek, tell, peek, and readinto support; verified against tarfile-style access patterns and aiocsv workflows.
• Reproducible Archives: Control gzip mtime and embedded filenames.
• Type-Safe: Distinct AsyncGzipBinaryFile and AsyncGzipTextFile.
• aiocsv Ready: Seamless integration for CSV pipelines.
• Predictable Performance: Backward seeks rewind the stream and re-decompress data (same as gzip.GzipFile), so treat random access as O(n) and prefer forward-only patterns when possible.

Quickstart

pip install aiogzip

import asyncio
from aiogzip import AsyncGzipFile

async def main():
    # Write
    async with AsyncGzipFile("file.gz", "wb") as f:
        await f.write(b"Hello, async world!")

    # Read
    async with AsyncGzipFile("file.gz", "rb") as f:
        print(await f.read())

asyncio.run(main())

# Deterministic metadata
async with AsyncGzipFile(
    "dataset.gz", "wb", mtime=0, original_filename="dataset.csv"
) as f:
    await f.write(b"stable bytes")

Performance

• Text I/O: Often ~2-3x faster than standard gzip in bulk text workflows.
• Binary I/O: Typically near parity for bulk reads/writes, and can be slower for very small chunk sizes.
• Concurrency: Non-blocking I/O can improve throughput in latency-bound multi-file workloads.
• Memory: Optimized buffer management for stable memory usage.
• JSONL: For large gzipped JSONL files, prefer AsyncGzipTextFile(..., newline="\n", chunk_size=512 * 1024) to reduce line-iteration overhead.

See the Performance Guide for detailed benchmarks.

Contributing

See CONTRIBUTING.md for development instructions.