Opened 15 months ago

Closed 15 months ago

Last modified 15 months ago

#28737 closed Cleanup/optimization (fixed)

Clarify {% cache %} tag's handling of arguments

Reported by: Tom Aratyn Owned by: nobody
Component: Documentation Version: 2.0
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The Django docs describe the use of the cache template tag:

It’s perfectly fine to specify more than one argument to identify the fragment. Simply pass as many arguments to {% cache %} as you need.

However the code will only use a single value (https://github.com/django/django/blob/7cc155a04ce9579de3cdca59db9a4de11dc5eab9/django/templatetags/cache.py#L90):

    return CacheNode(vary_on = [var.resolve(context) for var in self.vary_on]
cache_key = make_template_fragment_key(self.fragment_name, vary_on)
        nodelist, parser.compile_filter(tokens[1]),
        tokens[2],  # fragment_name can't be a variable.
        [parser.compile_filter(t) for t in tokens[3:]],
        cache_name,
    )

What's more the example code in the docs uses an variable as part of the fragment name, but the code explicitly says that that doesn't work.

I'd prefer for the solution to be to bring the code inline with the docs, but at least the docs need updating.

Change History (6)

comment:1 Changed 15 months ago by Tim Graham

Component: Core (Cache system)Documentation
Has patch: set
Summary: Cache tag and documentation inconsistentClarify {% cache %} tag's handling of arguments
Triage Stage: UnreviewedAccepted
Type: BugCleanup/optimization

I think you misinterpreted the documentation. I've suggested a clarification. Let me know if it helps.

comment:2 Changed 15 months ago by Tom Aratyn

Thanks for the quick turn around, Tim!

However, I don't think that patch is correct. I set a breakpoint on https://github.com/django/django/blob/master/django/templatetags/cache.py#L45 and I never see anything other than the third token being used as the fragment name (and therefore cache key).

I think the correct documentation might be to just say "you can only use a single string as your fragment key"... or fix the code to bring it inline with the docs.

My code has the following fragment:

  {% cache 300 "some fragment" "another fragment test"%}

and in the debugger I see that self.fragment_name is "some fragment" not a concatenation of the values. That makes sense, since on https://github.com/django/django/blob/master/django/templatetags/cache.py#L90 only the third token is passed as the fragment name.

comment:3 Changed 15 months ago by Tim Graham

The additional arguments are passed to vary_on which is used to make cache_key.

comment:4 in reply to:  3 Changed 15 months ago by Tom Aratyn

Replying to Tim Graham:

The additional arguments are passed to vary_on which is used to make cache_key.


Right. I had the word vary so locked into my head as the VARY header that I just blanked that out.

To make it explicit where you can and can't use variables, what do you think of https://github.com/django/django/pull/9285 ?

comment:5 Changed 15 months ago by Tim Graham <timograham@…>

Resolution: fixed
Status: newclosed

In 171c7cc8:

Fixed #28737 -- Clarified {% cache %} tag's handling of arguments.

Thanks Tom Aratyn for the report.

comment:6 Changed 15 months ago by Tim Graham <timograham@…>

In 01987bc0:

[2.0.x] Fixed #28737 -- Clarified {% cache %} tag's handling of arguments.

Thanks Tom Aratyn for the report.

Backport of 171c7cc863eafc2346aa84ffd1d540644539f1a4 from master

Note: See TracTickets for help on using tickets.
Back to Top