or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

compression.mdcore-middleware.mddjango-integration.mdindex.md
tile.json

tessl/pypi-whitenoise

Radically simplified static file serving for WSGI applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/whitenoise@6.9.x

To install, run

npx @tessl/cli install tessl/pypi-whitenoise@6.9.0

index.mddocs/

WhiteNoise

WhiteNoise enables web applications to serve their own static files without requiring external services like nginx or Amazon S3. It provides a self-contained solution particularly useful for PaaS deployments like Heroku and OpenShift. The library offers comprehensive static file handling with built-in compression support for gzip and Brotli formats, proper HTTP header handling, and far-future cache headers for immutable content.

Package Information

  • Package Name: whitenoise
  • Language: Python
  • Installation: pip install whitenoise
  • Optional Dependencies: pip install whitenoise[brotli] for Brotli compression support

Core Imports

from whitenoise import WhiteNoise

For Django integration:

from whitenoise.middleware import WhiteNoiseMiddleware
from whitenoise.storage import CompressedStaticFilesStorage, CompressedManifestStaticFilesStorage

For compression utilities:

from whitenoise.compress import Compressor

Basic Usage

WSGI Application Integration

from whitenoise import WhiteNoise
from my_project import application

# Wrap your WSGI application
application = WhiteNoise(application)

# Add static files directory
application.add_files('/path/to/static/files', prefix='/static/')

# For development, enable autorefresh
# application = WhiteNoise(application, autorefresh=True)

Django Integration

Add WhiteNoise middleware to Django settings:

# settings.py
MIDDLEWARE = [
    'whitenoise.middleware.WhiteNoiseMiddleware',
    # ... other middleware
]

# Optional: Use compression-enabled storage
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

Architecture

WhiteNoise follows a modular architecture designed for flexibility and performance:

  • WSGI Middleware Core: The WhiteNoise class serves as WSGI middleware, intercepting requests for static files before they reach your application
  • Django Integration Layer: WhiteNoiseMiddleware and storage classes provide seamless Django framework integration with auto-configuration
  • Compression Pipeline: Built-in support for gzip and Brotli compression with intelligent compression decisions
  • Response System: Sophisticated HTTP response handling with range requests, caching headers, and content negotiation
  • Media Type Resolution: Comprehensive MIME type detection for proper Content-Type headers

Capabilities

Core WSGI Middleware

Primary static file serving functionality with the WhiteNoise WSGI middleware class. Handles file serving, caching, compression, and HTTP best practices for any WSGI-compatible application.

class WhiteNoise:
    def __init__(
        self,
        application,
        root=None,
        prefix=None,
        *,
        autorefresh: bool = False,
        max_age: int | None = 60,
        allow_all_origins: bool = True,
        charset: str = "utf-8",
        mimetypes: dict[str, str] | None = None,
        add_headers_function: Callable[[Headers, str, str], None] | None = None,
        index_file: str | bool | None = None,
        immutable_file_test: Callable | str | None = None,
    ): ...
    
    def add_files(self, root, prefix=None): ...
    def __call__(self, environ, start_response): ...

Core Middleware

Django Integration

Django-specific middleware and static file storage classes that provide seamless integration with Django's static file handling, including auto-configuration from Django settings and staticfiles integration.

class WhiteNoiseMiddleware(WhiteNoise):
    def __init__(self, get_response=None, settings=settings): ...
    def __call__(self, request): ...

class CompressedStaticFilesStorage(StaticFilesStorage):
    def post_process(self, paths: dict[str, Any], dry_run: bool = False, **options: Any): ...

class CompressedManifestStaticFilesStorage(ManifestStaticFilesStorage):
    def post_process(self, *args, **kwargs): ...

Django Integration

File Compression

Compression functionality for static files supporting both gzip and Brotli formats. Includes intelligent compression decisions, command-line tools, and integration with Django's static file collection process.

class Compressor:
    def __init__(
        self,
        extensions=None,
        use_gzip=True,
        use_brotli=True,
        log=print,
        quiet=False
    ): ...
    
    def should_compress(self, filename): ...
    def compress(self, path): ...

Compression

Types

# Type aliases for function parameters
from typing import Callable
from wsgiref.headers import Headers

# Header manipulation function type
HeadersFunction = Callable[[Headers, str, str], None]

# Immutable file test function types
ImmutableFileTest = Callable[[str, str], bool]  # (path, url) -> bool
ImmutableFilePattern = str  # Regex pattern string