diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internals/deprecation.txt | 3 | ||||
| -rw-r--r-- | docs/ref/middleware.txt | 13 | ||||
| -rw-r--r-- | docs/ref/settings.txt | 5 | ||||
| -rw-r--r-- | docs/ref/utils.txt | 5 | ||||
| -rw-r--r-- | docs/releases/1.11.txt | 9 | ||||
| -rw-r--r-- | docs/topics/conditional-view-processing.txt | 19 | ||||
| -rw-r--r-- | docs/topics/i18n/translation.txt | 4 | ||||
| -rw-r--r-- | docs/topics/performance.txt | 3 |
8 files changed, 46 insertions, 15 deletions
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index a7ef1b8be5..2d247d8f65 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -43,6 +43,9 @@ details on these changes. * The ``django.db.models.permalink()`` decorator will be removed. +* The ``USE_ETAGS`` setting will be removed. ``CommonMiddleware`` and + ``django.utils.cache.patch_response_headers()`` will no longer set ETags. + .. _deprecation-removed-in-2.0: 2.0 diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index 5d8939e3ef..432f5437ff 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -72,6 +72,12 @@ Adds a few conveniences for perfectionists: Older versions didn't set the ``Content-Length`` header. +.. deprecated:: 1.11 + + The :setting:`USE_ETAGS` setting is deprecated in favor of using + :class:`~django.middleware.http.ConditionalGetMiddleware` for ETag + processing. + .. attribute:: CommonMiddleware.response_redirect_class Defaults to :class:`~django.http.HttpResponsePermanentRedirect`. Subclass @@ -166,13 +172,18 @@ Conditional GET middleware .. class:: ConditionalGetMiddleware -Handles conditional GET operations. If the response has a ``ETag`` or +Handles conditional GET operations. If the response doesn't have an ``ETag`` +header, the middleware adds one if needed. If the response has a ``ETag`` or ``Last-Modified`` header, and the request has ``If-None-Match`` or ``If-Modified-Since``, the response is replaced by an :class:`~django.http.HttpResponseNotModified`. Also sets the ``Date`` and ``Content-Length`` response-headers. +.. versionchanged:: 1.11 + + In older versions, the middleware didn't set the ``ETag`` header. + Locale middleware ----------------- diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 05faa734b2..28240034e5 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2532,6 +2532,11 @@ bandwidth but slows down performance. This is used by the :class:`~django.middleware.common.CommonMiddleware` and in the :doc:`cache framework </topics/cache>`. +.. deprecated:: 1.11 + + This setting is deprecated in favor of using ``ConditionalGetMiddleware``, + which sets an ETag regardless of this setting. + .. setting:: USE_I18N ``USE_I18N`` diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index a9072f9442..45ffd80fc4 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -65,6 +65,11 @@ need to distinguish caches by the ``Accept-language`` header. In older versions, the ``Last-Modified`` header was also set. + .. deprecated:: 1.11 + + Since the ``USE_ETAGS`` setting is deprecated, this function won't set + the ``ETag`` header when the deprecation ends in Django 2.1. + .. function:: add_never_cache_headers(response) Adds a ``Cache-Control: max-age=0, no-cache, no-store, must-revalidate`` diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt index ff77ebeabb..3be654eff5 100644 --- a/docs/releases/1.11.txt +++ b/docs/releases/1.11.txt @@ -327,6 +327,9 @@ Requests and Responses * Added the :setting:`SECURE_HSTS_PRELOAD` setting to allow appending the ``preload`` directive to the ``Strict-Transport-Security`` header. +* :class:`~django.middleware.http.ConditionalGetMiddleware` now adds the + ``ETag`` header to responses. + Serialization ~~~~~~~~~~~~~ @@ -633,3 +636,9 @@ Miscellaneous * :func:`~django.contrib.auth.authenticate` now passes a ``request`` argument to the ``authenticate()`` method of authentication backends. Support for methods that don't accept ``request`` will be removed in Django 2.1. + +* The ``USE_ETAGS`` setting is deprecated in favor of + :class:`~django.middleware.http.ConditionalGetMiddleware` which now adds the + ``ETag`` header to responses regardless of the setting. ``CommonMiddleware`` + and ``django.utils.cache.patch_response_headers()`` will no longer set ETags + when the deprecation ends. diff --git a/docs/topics/conditional-view-processing.txt b/docs/topics/conditional-view-processing.txt index 7398b3fd05..7f1fde0fb9 100644 --- a/docs/topics/conditional-view-processing.txt +++ b/docs/topics/conditional-view-processing.txt @@ -11,7 +11,7 @@ used for all HTTP methods (``POST``, ``PUT``, ``DELETE``, etc.). For each page (response) that Django sends back from a view, it might provide two HTTP headers: the ``ETag`` header and the ``Last-Modified`` header. These headers are optional on HTTP responses. They can be set by your view function, -or you can rely on the :class:`~django.middleware.common.CommonMiddleware` +or you can rely on the :class:`~django.middleware.http.ConditionalGetMiddleware` middleware to set the ``ETag`` header. When the client next requests the same resource, it might send along a header @@ -189,17 +189,14 @@ every time. Comparison with middleware conditional processing ================================================= -You may notice that Django already provides simple and straightforward -conditional ``GET`` handling via the -:class:`django.middleware.http.ConditionalGetMiddleware` and -:class:`~django.middleware.common.CommonMiddleware`. While certainly being -easy to use and suitable for many situations, those pieces of middleware -functionality have limitations for advanced usage: +Django provides simple and straightforward conditional ``GET`` handling via +:class:`django.middleware.http.ConditionalGetMiddleware`. While being easy to +use and suitable for many situations, the middleware has limitations for +advanced usage: -* They are applied globally to all views in your project -* They don't save you from generating the response itself, which may be - expensive -* They are only appropriate for HTTP ``GET`` requests. +* It's applied globally to all views in your project. +* It doesn't save you from generating the response, which may be expensive. +* It's only appropriate for HTTP ``GET`` requests. You should choose the most appropriate tool for your particular problem here. If you have a way to compute ETags and modification times quickly and if some diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt index 4ef0ae45a3..db891f75d7 100644 --- a/docs/topics/i18n/translation.txt +++ b/docs/topics/i18n/translation.txt @@ -1372,8 +1372,8 @@ URL:: ] Client-side caching will save bandwidth and make your site load faster. If -you're using ETags (:setting:`USE_ETAGS = True <USE_ETAGS>`), you're already -covered. Otherwise, you can apply :ref:`conditional decorators +you're using ETags (:class:`~django.middleware.http.ConditionalGetMiddleware`), +you're already covered. Otherwise, you can apply :ref:`conditional decorators <conditional-decorators>`. In the following example, the cache is invalidated whenever you restart your application server:: diff --git a/docs/topics/performance.txt b/docs/topics/performance.txt index c8c9d231af..8f2516a4eb 100644 --- a/docs/topics/performance.txt +++ b/docs/topics/performance.txt @@ -262,7 +262,8 @@ that can help optimize your site's performance. They include: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Adds support for modern browsers to conditionally GET responses based on the -``ETag`` and ``Last-Modified`` headers. +``ETag`` and ``Last-Modified`` headers. It also calculates and sets an ETag if +needed. :class:`~django.middleware.gzip.GZipMiddleware` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |