Opened 2 years ago

Closed 2 years ago

#19862 closed Cleanup/optimization (wontfix)

docs for signal request_finished

Reported by: guettli Owned by: nobody
Component: Documentation Version: 1.4
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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".

Change History (2)

comment:1 Changed 2 years ago by guettli

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 2 years ago by aaugustin

  • Resolution set to wontfix
  • Status changed from new to closed

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.

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