Skip to main content

starlette-cramjam

Cramjam integration for Starlette ASGI framework.

Test Coverage Package version Downloads Downloads


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 an Extremely thin Python bindings to de/compression algorithms in Rust.

Installation

You can install starlette-cramjam from pypi

$ pip install -U pip
$ pip install starlette-cramjam

or install from source:

$ 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

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

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

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.

Contribution & Development

See CONTRIBUTING.md

License

See LICENSE

Authors

Created by Development Seed

See contributors for a listing of individual contributors.

Metadata

Release files for starlette-cramjam 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for starlette-cramjam 0.8.0
File Size Uploaded Provenance Actions
starlette_cramjam-0.8.0.tar.gz 7.8 kB With provenance Details for starlette_cramjam-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for starlette-cramjam 0.8.0
File Interpreter ABI Platform Actions
starlette_cramjam-0.8.0-py3-none-any.whl Python 3 none any Details for starlette_cramjam-0.8.0-py3-none-any.whl

Total release size: 16.0 kB

Release files / starlette_cramjam-0.8.0.tar.gz

Download URL starlette_cramjam-0.8.0.tar.gz
Size 7.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e853ed4c9d581fdc95d20a94f9e73bc815dc933d7d54d5afc57f3662bab676a1
BLAKE2b-256 checksum
How to use checksums
840cf96f9f6ea0f42ba1722c6bbdcaff0cab1be6765cf26afc27c41c8a8f64c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / starlette_cramjam-0.8.0-py3-none-any.whl

Download URL starlette_cramjam-0.8.0-py3-none-any.whl
Size 8.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8f8eaa666fded065f37d6065027fa5c2d8af9fd737576b0f36a657b07183b7f9
BLAKE2b-256 checksum
How to use checksums
01a28575b627505c5448367591603d31ac7f619f690951690aeeb30e5a775db4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for starlette-cramjam 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for starlette_cramjam-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page