aiohttp-fast-zlib

0.3.0 · active · verified Thu Apr 16

aiohttp-fast-zlib is a Python library (current version 0.3.0) that replaces the default `zlib` usage in `aiohttp` with faster alternatives like `isal` or `zlib-ng`. This significantly improves compression and decompression performance, especially for `aiohttp`'s WebSocket connections, where `zlib` can be a bottleneck. The library has seen several updates over the past year, indicating active maintenance and development.

Common errors

```
WARNING (MainThread) [aiohttp_fast_zlib] zlib_ng and isal are not available, falling back to zlib, performance will be degraded.
```
cause The optional faster compression libraries (`isal` or `zlib-ng`) were not installed when `aiohttp-fast-zlib` was installed.

fix Install `aiohttp-fast-zlib` with the desired extra: `pip install aiohttp-fast-zlib[isal]` (recommended) or `pip install aiohttp-fast-zlib[zlib-ng]`.
```
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts: <another_library> requires aiohttp==X.Y.Z, but you have aiohttp A.B.C which is incompatible.
```
cause Conflicting `aiohttp` version requirements between `aiohttp-fast-zlib` and other installed libraries in your environment.

fix Carefully check the `aiohttp` version required by all libraries in your project. Attempt to find an `aiohttp` version that satisfies all dependencies, or isolate conflicting dependencies using virtual environments.

Warnings

gotcha Performance will be degraded if neither 'isal' nor 'zlib-ng' are installed alongside 'aiohttp-fast-zlib'. The library will silently fall back to the slower standard Python 'zlib' module.
Fix: Install with an extra: `pip install aiohttp-fast-zlib[isal]` or `pip install aiohttp-fast-zlib[zlib-ng]`.
breaking aiohttp-fast-zlib v0.3.0 introduces support for aiohttp 3.12 and newer. Older versions of aiohttp-fast-zlib had different aiohttp compatibility requirements. Always check the project's PyPI or GitHub page for precise aiohttp version compatibility with the specific aiohttp-fast-zlib version you are using.
Fix: Ensure your `aiohttp` version meets the requirements of `aiohttp-fast-zlib`. For v0.3.0, ensure `aiohttp>=3.12.0` is installed. If using an older `aiohttp-fast-zlib`, you may need an older `aiohttp`.
gotcha Aiohttp itself (>=3.12) provides `aiohttp.set_zlib_backend()` for manually specifying a zlib-compatible module. `aiohttp-fast-zlib` offers automatic detection and fallback, but direct `aiohttp.set_zlib_backend()` calls will override its effects.
Fix: If using `aiohttp-fast-zlib`, rely on its `enable()` function for automatic backend selection. Avoid `aiohttp.set_zlib_backend()` unless you explicitly want to manage the zlib backend yourself and override `aiohttp-fast-zlib`'s behavior.

Install

pip install aiohttp-fast-zlib Base installation
pip install aiohttp-fast-zlib[isal] With isal for maximum speed
pip install aiohttp-fast-zlib[zlib-ng] With zlib-ng as an alternative fast backend

Imports

enable
```
import aiohttp_zlib_fast
aiohttp_zlib_fast.enable()
```
Call `enable()` once at application startup to patch aiohttp's zlib backend.

Quickstart

This quickstart demonstrates how to enable `aiohttp-fast-zlib` and then use a standard `aiohttp.ClientSession` to make a request. The `enable()` call patches `aiohttp` globally to use the faster zlib backend. You can set the `TEST_URL` environment variable to point to a service that returns gzipped content (e.g., `httpbin.org/gzip`) to observe its effect.

import aiohttp
import asyncio
import os
import aiohttp_zlib_fast

# Enable the fast zlib backend. isal is preferred if available, then zlib-ng, else standard zlib.
aiohttp_zlib_fast.enable()

async def fetch(session, url):
    async with session.get(url) as response:
        print(f"Status: {response.status}")
        print(f"Content-type: {response.headers.get('content-type')}")
        # If the response is compressed, aiohttp will decompress it using the enabled backend
        text = await response.text()
        print(f"Body snippet: {text[:100]}...")

async def main():
    async with aiohttp.ClientSession() as session:
        # Use a real URL, or an httpbin-like service that supports compression
        await fetch(session, os.environ.get('TEST_URL', 'http://httpbin.org/gzip'))

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →