Skip to main content

An ASGI app for static file serving inspired by whitenoise

Project description

blacknoise

PyPI - Version PyPI - Python Version

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

blacknoise-1.1.0.tar.gz (8.3 kB view details)

Uploaded Source

Built Distribution

blacknoise-1.1.0-py3-none-any.whl (6.4 kB view details)

Uploaded Python 3

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

Hashes for blacknoise-1.1.0.tar.gz
Algorithm Hash digest
SHA256 20b96a452fe04d40bd69c3d939fb5e751ef56a835975d23fd4354af6e7a0c534
MD5 6aba77009d97a7267c9ea6e2a22b47df
BLAKE2b-256 7dc7f60d6dc2c3f88ee6768c047f33204a985a1a17212fbd8b1c6aba7c2e3681

See more details on using hashes here.

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

Hashes for blacknoise-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 789e7cb4c0354164738d001fee37622dd8d10df829b33a47ca2645dcfa76e9b0
MD5 3b92b04956e4e970a6832ed04c175c0b
BLAKE2b-256 25c24a4f2e5c10dfffef0de72784dc7faeac7b499b58160d684df7f981b73096

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page