Wrong example of Cache-Control in the docs

[Vasiliy Faronov]

Django’s ​caching docs provide the following example of setting the Cache-Control header:

In this example, cache_control tells caches to revalidate the cache on every access and to store cached versions for, at most, 3,600 seconds:

from django.views.decorators.cache import cache_control
    
@cache_control(must_revalidate=True, max_age=3600)
def my_view(request):
    # ...

This is wrong. What it really tells caches is:

• ​max-age=3600: the response is “fresh,” and can be served directly from cache (without revalidation), for 3600 seconds;
• ​must-revalidate: after these 3600 seconds, when the response becomes “stale,” it cannot be served from cache (without revalidation) even if otherwise that would be allowed, such as when the cache is disconnected from the network.

In my tests, with these directives, both Chrome and Firefox serve the page from cache after the first access.

The right directive for “revalidate on every access” is ​no-cache. And as far as I know, there is no directive to limit the time for which a response is stored; only the ​no-store directive that forbids storage entirely.

[Vasiliy Faronov]

I can’t come up with a correct example that would also be convincing. Maybe it’s best to remove the example and just mention that you can directly set Cache-Control with that decorator.

[Tim Graham]

I don't understand why correcting the description of the existing example isn't a good idea?

[Vasiliy Faronov]

Replying to timgraham:

I don't understand why correcting the description of the existing example isn't a good idea?

Because readers won’t see the motivation for such an example. Normally max-age is set automatically by the caching middleware, and when people want to prevent caching, they just use @never_cache.

Maybe something along these lines would work:

Even if you’re not using Django’s server-side caching features, you can tell clients to cache a view for a certain amount of time:

from django.views.decorators.cache import cache_control
    
@cache_control(max_age=3600)
def my_view(request):
    # ...

[Tim Graham]

Sure, feel free to submit a pull request as you see fit.

[Vasiliy Faronov]

Alright, my attempt is in ​PR #6561.

[Tim Graham <timograham@…>]

In 101dd787:

Fixed #26566 -- Rewrote an incorrect Cache-Control example.

[Tim Graham <timograham@…>]

In bb95d409:

[1.9.x] Fixed #26566 -- Rewrote an incorrect Cache-Control example.

Backport of 101dd787eca588f32c4647fe45fc533072f0eb0b from master