Add RequestHandler.on_finish method.

bdarnell · bdarnell · commit 6dfc1b75d2a7 · 2012-01-18T00:43:38.000-08:00
Closes tornadoweb#367.
diff --git a/tornado/web.py b/tornado/web.py
@@ -171,18 +171,31 @@ def options(self, *args, **kwargs):
         raise HTTPError(405)
 
     def prepare(self):
-        """Called before the actual handler method.
+        """Called at the beginning of a request before `get`/`post`/etc.
 
-        Useful to override in a handler if you want a common bottleneck for
-        all of your requests.
+        Override this method to perform common initialization regardless
+        of the request method.
+        """
+        pass
+
+    def on_finish(self):
+        """Called after the end of a request.
+
+        Override this method to perform cleanup, logging, etc.
+        This method is a counterpart to `prepare`.  ``on_finish`` may
+        not produce any output, as it is called after the response
+        has been sent to the client.
         """
         pass
 
     def on_connection_close(self):
         """Called in async handlers if the client closed the connection.
 
-        You may override this to clean up resources associated with
-        long-lived connections.
+        Override this to clean up resources associated with
+        long-lived connections.  Note that this method is called only if
+        the connection was closed during asynchronous processing; if you
+        need to do cleanup after every request override `on_finish`
+        instead.
 
         Proxies may keep a connection open for a time (perhaps
         indefinitely) after the client has gone away, so this method
@@ -656,6 +669,7 @@ def finish(self, chunk=None):
             self.request.finish()
             self._log()
         self._finished = True
+        self.on_finish()
 
     def send_error(self, status_code=500, **kwargs):
         """Sends the given HTTP error code to the browser.
diff --git a/website/sphinx/overview.rst b/website/sphinx/overview.rst
@@ -140,6 +140,9 @@ place:
 4. One of the HTTP methods is called: ``get()``, ``post()``, ``put()``,
    etc. If the URL regular expression contains capturing groups, they
    are passed as arguments to this method.
+5. When the request is finished, ``on_finish()`` is called.  For synchronous
+   handlers this is immediately after ``get()`` (etc) return; for
+   asynchronous handlers it is after the call to ``finish()``.
 
 Here is an example demonstrating the ``initialize()`` method:
 
diff --git a/website/sphinx/releases/next.rst b/website/sphinx/releases/next.rst
@@ -49,6 +49,15 @@ Backwards-incompatible changes
   ``{% comment %}`` directive, these can wrap other template directives).
 * Template directives may now span multiple lines.
 
+``tornado.web``
+~~~~~~~~~~~~~~~
+
+* Now behaves better when given malformed ``Cookie`` headers
+* `RequestHandler.redirect` now has a ``status`` argument to send
+  status codes other than 301 and 302.
+* New method `RequestHandler.on_finish` may be overridden for post-request
+  processing (as a counterpart to `RequestHandler.prepare`)
+
 ``tornado.websocket``
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -67,9 +76,6 @@ Other modules
   responses with no content, or empty ``POST``/``PUT`` response bodies.
 * `tornado.platform.twisted` compatibility has been significantly improved.
   Twisted version 11.1.0 is now supported in addition to 11.0.0.
-* `tornado.web` now behaves better when given malformed ``Cookie`` headers
-* `RequestHandler.redirect` now has a ``status`` argument to send
-  status codes other than 301 and 302.
 * `tornado.testing.main` supports a new flag ``--exception_on_interrupt``,
   which can be set to false to make ``Ctrl-C`` kill the process more
   reliably (at the expense of stack traces when it does so).
