An ASGI app for static file serving inspired by whitenoise
Project description
blacknoise
blacknoise is an ASGI app for static file serving inspired by whitenoise and following the principles of low maintenance software.
Using blacknoise to serve static files
Install blacknoise into your Python environment:
pip install blacknoise
Wrap your ASGI application with the BlackNoise
app:
from blacknoise import BlackNoise
from django.core.asgi import get_asgi_application
from pathlib import Path
BASE_DIR = Path(__file__).parent
application = BlackNoise(get_asgi_application())
application.add(BASE_DIR / "static", "/static")
The example uses Django, but you can wrap any ASGI application.
BlackNoise
will automatically handle all paths below the prefixes added, and
either return the files or return 404 errors if files do not exist. The files
are added on server startup, which also means that BlackNoise
only knows
about files which existed at that particular point in time.
BlackNoise
doesn't watch the added folders for changes; if you add new files
you have to restart the server, otherwise those files aren't served. It doesn't
cache file contents though, so changes to files are directly picked up.
Improving performance
BlackNoise
has worse performance than when using an optimized webserver such
as nginx and others. Sometimes it doesn't matter much if the app is behind a
caching reverse proxy or behind a content delivery network anyway. To further
support this use case BlackNoise
can be configured to serve media files with
far-future expiry headers and has support for serving compressed assets.
Serving pre-compressed assets
Compressing is possible by running:
python -m blacknoise.compress static/
BlackNoise
will try compress non-binary files using gzip or brotli (if the
Brotli library is available), and will serve
the compressed version if the compression actually results in (significantly)
smaller files and if the client also supports it. Files are compressed in
parallel for faster completion times.
Setting far-future expiry headers
Far-future expiry headers can be enabled by passing the immutable_file_test
callable to the BlackNoise
constructor:
def immutable_file_test(path):
return True # Enable far-future expiry headers for all files
application = BlackNoise(
get_asgi_application(),
immutable_file_test=immutable_file_test,
)
Maybe you want to add some other logic, for example check if the path contains
a hash based upon the contents of the static file. Such hashes can be added by
Django's ManifestStaticFilesStorage
or by appropriately configuring bundlers
such as webpack
and others.
License
blacknoise
is distributed under the terms of the
MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file blacknoise-1.1.0.tar.gz
.
File metadata
- Download URL: blacknoise-1.1.0.tar.gz
- Upload date:
- Size: 8.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: python-httpx/0.27.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 20b96a452fe04d40bd69c3d939fb5e751ef56a835975d23fd4354af6e7a0c534 |
|
MD5 | 6aba77009d97a7267c9ea6e2a22b47df |
|
BLAKE2b-256 | 7dc7f60d6dc2c3f88ee6768c047f33204a985a1a17212fbd8b1c6aba7c2e3681 |
File details
Details for the file blacknoise-1.1.0-py3-none-any.whl
.
File metadata
- Download URL: blacknoise-1.1.0-py3-none-any.whl
- Upload date:
- Size: 6.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: python-httpx/0.27.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 789e7cb4c0354164738d001fee37622dd8d10df829b33a47ca2645dcfa76e9b0 |
|
MD5 | 3b92b04956e4e970a6832ed04c175c0b |
|
BLAKE2b-256 | 25c24a4f2e5c10dfffef0de72784dc7faeac7b499b58160d684df7f981b73096 |