From f6cb1efa8fba683bdc5c9b4a645f9357fe2e6208 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Wed, 4 Dec 2019 01:13:52 -0600 Subject: negotiate the best static asset using supported encodings --- docs/narr/assets.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index d1d64f0c3..f9d30563e 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -189,6 +189,37 @@ listening on ``example.com`` must be itself configured to respond properly to such a request. The :meth:`~pyramid.request.Request.static_url` API is discussed in more detail later in this chapter. +.. index:: + single: pre-compressed assets + +.. _pre_compressed_assets: + +Serving Pre-compressed Assets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.0 + +It's possible to configure :app:`Pyramid` to serve pre-compressed static assets. +This can greatly reduce the bandwidth required to serve assets - most modern browsers support ``gzip``, ``deflate``, and ``br`` (brotli) encoded responses. +A client declares support for encoded responses using the ``Accept-Encoding`` HTTP header. For example, ``Accept-Encoding: gzip, default, br``. +The response will then contain the pre-compressed content with the ``Content-Encoding`` header set to the matched encoding. +This feature assumes that the static assets exist unencoded (``identity`` encoding) as well as in zero or more encoded formats. +If the encoded version of a file is missing, or the client doesn't declare support for the encoded version, the unencoded version is returned instead. + +In order to configure this in your application, the first step is to compress your assets. +For example, update your static asset pipeline to export ``.gz`` versions of every file. +Second, add ``content_encodings=['gzip']`` when invoking :meth:`pyramid.config.Configurator.add_static_view`. + +The encoded file extensions are determined by :attr:`mimetypes.encodings_map`. +So, if your desired encoding is missing, you'll need to add it there: + +.. code-block:: python + + import mimetypes + mimetypes.encodings_map['.br'] = 'br' # add brotli + +It is not necessary for every file to support every encoding, but :app:`Pyramid` will not serve an encoding that is not declared. + .. index:: single: generating static asset urls single: static asset urls -- cgit v1.2.3