https://github.com/developmentseed/starlette-cramjam
Compression middleware based on cramjam for Starlette ASGI framework.
https://github.com/developmentseed/starlette-cramjam
Last synced: 10 months ago
JSON representation
Compression middleware based on cramjam for Starlette ASGI framework.
- Host: GitHub
- URL: https://github.com/developmentseed/starlette-cramjam
- Owner: developmentseed
- License: mit
- Created: 2021-05-26T01:16:20.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-04-18T13:30:37.000Z (about 1 year ago)
- Last Synced: 2025-06-03T12:13:49.186Z (11 months ago)
- Language: Python
- Homepage:
- Size: 55.7 KB
- Stars: 15
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starlette - Starlette Cramjam - Middleware adding Brotli, Gzip, and Deflate compression with minimal requirements via the `cramjam` library. (Extensions / Compression)
README
# starlette-cramjam
Cramjam integration for Starlette ASGI framework.
---
**Source Code**: https://github.com/developmentseed/starlette-cramjam
---
The `starlette-cramjam` middleware aims to provide a unique Compression middleware to support **Brotli**, **GZip**, **Deflate** and **ZSTD** compression algorithms with a minimal requirement.
The middleware will compress responses for any request that includes "br", "gzip", "deflate" or "zstd" in the Accept-Encoding header.
As for the official `Starlette` middleware, the one provided by `starlette-cramjam` will handle both standard and streaming responses.
`stralette-cramjam` is built on top of [pyrus-cramjam](https://github.com/milesgranger/pyrus-cramjam) an *Extremely thin Python bindings to de/compression algorithms in Rust*.
## Installation
You can install `starlette-cramjam` from pypi
```python
$ pip install -U pip
$ pip install starlette-cramjam
```
or install from source:
```bash
$ pip install -U pip
$ pip install https://github.com/developmentseed/starlette-cramjam.git
```
## Usage
The following arguments are supported:
- **compression** (List of Compression) - List of available compression algorithm. **This list also defines the order of preference**. Defaults to `[Compression.gzip, Compression.deflate, Compression.br, Compression.zstd]`,
- **compression_level** (Integer) - Compression level to use, form `0` (None) to `11` (High). Defaults to cramjam internal defaults for each compression backend.
- **minimum_size** (Integer) - Do not compress responses that are smaller than this minimum size in bytes. Defaults to `500`.
- **exclude_path** (Set of string) - Do not compress responses in response to specific `path` requests. Entries have to be valid regex expressions. Defaults to `{}`.
- **exclude_mediatype** (Set of string) - Do not compress responses of specific media type (e.g `image/png`). Defaults to `{}`.
#### Minimal (defaults) example
```python
import uvicorn
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.responses import PlainTextResponse
from starlette.routing import Route
from starlette_cramjam.middleware import CompressionMiddleware
def index(request):
return PlainTextResponse("Hello World")
app = Starlette(
routes=[Route("/", endpoint=index)],
middleware=[
Middleware(CompressionMiddleware),
],
)
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
```
#### Using options
```python
import uvicorn
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.responses import PlainTextResponse, Response
from starlette.routing import Route
from starlette_cramjam.compression import Compression
from starlette_cramjam.middleware import CompressionMiddleware
def index(request):
return PlainTextResponse("Hello World")
def img(request):
return Response(b"This is a fake body", status_code=200, media_type="image/jpeg")
def foo(request):
return PlainTextResponse("Do not compress me.")
app = Starlette(
routes=[
Route("/", endpoint=index),
Route("/image", endpoint=img),
Route("/foo", endpoint=foo),
],
middleware=[
Middleware(
CompressionMiddleware,
compression=[Compression.gzip], # Only support `gzip`
compression_level=6, # Compression level to use
minimum_size=0, # should compress everything
exclude_path={"^/foo$"}, # do not compress response for the `/foo` request
exclude_mediatype={"image/jpeg"}, # do not compress jpeg
),
],
)
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
```
## Performance
```python
import gzip
import sys
import brotli
import cramjam
import httpx
page = httpx.get("https://github.com/developmentseed/starlette-cramjam").content
len(page)
# 347686
%timeit brotli.compress(page, quality=4)
# 1.77 ms ± 19.7 µs per loop (mean ± std. dev. of 7 runs, 1000 loops each)
sys.getsizeof(brotli.compress(page, quality=4))
# 48766
%timeit gzip.compress(page, compresslevel=6)
# 4.62 ms ± 28 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
sys.getsizeof(gzip.compress(page, compresslevel=6))
# 54888
# ------------
# With Cramjam
# ------------
%timeit cramjam.gzip.compress(page, level=6)
# 4.12 ms ± 57.3 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
cramjam.gzip.compress(page, level=6).len()
# 55221
%timeit cramjam.brotli.compress(page, level=4)
# 2.3 ms ± 48.5 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
cramjam.brotli.compress(page, level=4).len()
# 48742
```
Ref: https://github.com/fullonic/brotli-asgi?tab=readme-ov-file#performance
## Changes
See [CHANGES.md](https://github.com/developmentseed/starlette-cramjam/blob/master/CHANGES.md).
## Contribution & Development
See [CONTRIBUTING.md](https://github.com/developmentseed/starlette-cramjam/blob/master/CONTRIBUTING.md)
## License
See [LICENSE](https://github.com/developmentseed/starlette-cramjam/blob/master/LICENSE)
## Authors
Created by [Development Seed]()
See [contributors](https://github.com/developmentseed/starlette-cramjam/graphs/contributors) for a listing of individual contributors.