docs for signal request_finished

[Thomas Güttler]

current doc at master branch:

request_finished
----------------

.. data:: django.core.signals.request_finished
   :module:

Sent when Django finishes processing an HTTP request.

.. note::

    When a view returns a :ref:`streaming response <httpresponse-streaming>`,
    this signal is sent only after the entire response is consumed by the
    client (strictly speaking, by the WSGI gateway).

.. versionchanged:: 1.5

    Before Django 1.5, this signal was fired before sending the content to the
    client. In order to accomodate streaming responses, it is now fired after
    sending the content.

What happens for non streaming responses?

Case1: the signal is sent after sending the content: Please remove the note (before .. versionchanged).

Case2: the signal is sent before sending the content: Please update the last sentence: "it is not fired after sending the content for streaming responses".

[Thomas Güttler]

current docs of request_finished: ​https://github.com/django/django/blob/master/docs/ref/signals.txt#L445

[Aymeric Augustin]

In Django < 1.5, the signal is sent before returning the WSGI iterable to the gateway:

• This didn't matter for non-streaming responses because the content was already fully generated at this point. After sending the signal, Django simply passes the content to the WSGI gateway.
• If you attempted to use a streaming response (which was difficult but not impossible), the signal was sent before generating the content. This had some unintended consequences.

In Django >= 1.5, the signal is sent in the close() method of the WSGI iterable.

---

Since Django implements your case 1, your suggestion is to remove this note. I disagree. This is an important gotcha for people using streaming responses. They could expect the request_finished signal to be fired when the request handler terminates, rather than when the response iterator is exhausted.

The versionchanged directive will be removed in Django 1.7; the note will remain.

When a view returns a regular response, there isn't a concept of "consuming the response", because the WSGI iterable is just a plain list (containing only one item). The note is only relevant for streaming responses. I added "when a view..." to make it clear to people who don't use streaming responses that they can simply ignore the note.