0
# WhiteNoise
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: whitenoise
7
- **Language**: Python
8
- **Installation**: `pip install whitenoise`
9
- **Optional Dependencies**: `pip install whitenoise[brotli]` for Brotli compression support
10

11
## Core Imports
12

13
```python
14
from whitenoise import WhiteNoise
15
```
16

17
For Django integration:
18

19
```python
20
from whitenoise.middleware import WhiteNoiseMiddleware
21
from whitenoise.storage import CompressedStaticFilesStorage, CompressedManifestStaticFilesStorage
22
```
23

24
For compression utilities:
25

26
```python
27
from whitenoise.compress import Compressor
28
```
29

30
## Basic Usage
31

32
### WSGI Application Integration
33

34
```python
35
from whitenoise import WhiteNoise
36
from my_project import application
37

38
# Wrap your WSGI application
39
application = WhiteNoise(application)
40

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

44
# For development, enable autorefresh
45
# application = WhiteNoise(application, autorefresh=True)
46
```
47

48
### Django Integration
49

50
Add WhiteNoise middleware to Django settings:
51

52
```python
53
# settings.py
54
MIDDLEWARE = [
55
    'whitenoise.middleware.WhiteNoiseMiddleware',
56
    # ... other middleware
57
]
58

59
# Optional: Use compression-enabled storage
60
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'
61
```
62

63
## Architecture
64

65
WhiteNoise follows a modular architecture designed for flexibility and performance:
66

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

73
## Capabilities
74

75
### Core WSGI Middleware
76

77
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.
78

79
```python { .api }
80
class WhiteNoise:
81
    def __init__(
82
        self,
83
        application,
84
        root=None,
85
        prefix=None,
86
        *,
87
        autorefresh: bool = False,
88
        max_age: int | None = 60,
89
        allow_all_origins: bool = True,
90
        charset: str = "utf-8",
91
        mimetypes: dict[str, str] | None = None,
92
        add_headers_function: Callable[[Headers, str, str], None] | None = None,
93
        index_file: str | bool | None = None,
94
        immutable_file_test: Callable | str | None = None,
95
    ): ...
96
    
97
    def add_files(self, root, prefix=None): ...
98
    def __call__(self, environ, start_response): ...
99
```
100

101
[Core Middleware](./core-middleware.md)
102

103
### Django Integration
104

105
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.
106

107
```python { .api }
108
class WhiteNoiseMiddleware(WhiteNoise):
109
    def __init__(self, get_response=None, settings=settings): ...
110
    def __call__(self, request): ...
111

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

115
class CompressedManifestStaticFilesStorage(ManifestStaticFilesStorage):
116
    def post_process(self, *args, **kwargs): ...
117
```
118

119
[Django Integration](./django-integration.md)
120

121
### File Compression
122

123
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.
124

125
```python { .api }
126
class Compressor:
127
    def __init__(
128
        self,
129
        extensions=None,
130
        use_gzip=True,
131
        use_brotli=True,
132
        log=print,
133
        quiet=False
134
    ): ...
135
    
136
    def should_compress(self, filename): ...
137
    def compress(self, path): ...
138
```
139

140
[Compression](./compression.md)
141

142
## Types
143

144
```python { .api }
145
# Type aliases for function parameters
146
from typing import Callable
147
from wsgiref.headers import Headers
148

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

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