TemplateResponse handles context/context processors differently from 'render' shortcut

[Luke Plant]

The documentation for TemplateResponse states that TemplateResponse can be used as an alternative to render_to_response. (In fact, it would be better to point out that it is a closer equivalent to render).

​https://docs.djangoproject.com/en/dev/ref/template-response/#using-templateresponse-and-simpletemplateresponse

Similarly, the docs for render suggest that the TemplateResponse constructor can be used as a drop in equivalent: "the constructor of TemplateResponse offers the same level of convenience as render()"

​https://docs.djangoproject.com/en/dev/topics/http/shortcuts/#render

There is a subtle but significant difference, however:

If a context processor returns a dictionary with a key that is the same as one in the context dictionary passed in to the TemplateResponse constructor, then the priority is different: TemplateResponse will overwrite (or shadow) the passed in context dictionary using the data from the context processors, while render does it the other way around.

In my opinion, the behaviour in render is much more useful: there are a number of circumstances when I might use a context processor to define some default global data for templates, but then I might want to override that in a specific view.

There is value the other way around, of course: if a 3rd party app provides puts some data into a context that you want to change by configuring a context processor. However, the whole point of TemplateResponse is to make it easy to make changes like that in other ways - a simple view wrapper or middleware will allow you to do it. The behaviour of render is also older and therefore much more likely to have patterns established around it.

I'd like us fix TemplateResponse to be in line with render, as it represents a significant gotcha if you transition from render to TemplateResponse. (In one project I've had to fix it using a custom TemplateResponse subclass, but it took me a good while to debug the problem). This, of course, is a backwards incompatible change for the case where someone was relying on the current behaviour. However, given that we do not currently test or document the current behaviour of TemplateResponse in this regard, and the docs suggest the opposite (you can use the TemplateResponse constructor as a way to get the behaviour of render but with a TemplateResponse instance returned instead of an HttpResponse), I think we can easily argue that the current behaviour of TemplateResponse is a bug that should be fixed.

I'll attach a patch that implements it for reference, which is very simple. Note that apart from the new test I've added, there are no failures in our test suite caused by the change in behaviour i.e. nothing in Django itself depends on the current behaviour. Obviously I'll add a backwards compatibility note if others agree with this change, and then commit.

[Luke Plant]

Patch implementing bug fix

[Luke Plant <L.Plant.98@…>]

In b748a8bc670af10c37560836c353ce911eaeecc0:

Fixed #23789 -- TemplateResponse handles context differently from render

[Aymeric Augustin]

The following paragraph no longer applies after this change:

​https://github.com/django/django/blob/b748a8bc670af10c37560836c353ce911eaeecc0/docs/ref/class-based-views/mixins-simple.txt#L61-L70

It should be removed from the documentation.

[Tim Graham <timograham@…>]

In 493ab45349e7768cba137207b8a27282921e9388:

Updated TemplateResponseMixin docs to reflect new behavior after refs #23789.