CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-whitenoise

Radically simplified static file serving for WSGI applications

Overview
Eval results
Files

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

Install with Tessl CLI

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