From: Ben Darnell <ben@bendarnell.com>
Date: Mon, 28 Apr 2025 19:44:21 +0000 (-0400)
Subject: web: Update docstrings for prepare and on_finish
X-Git-Tag: v6.5.0b1~4^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F3490%2Fhead;p=thirdparty%2Ftornado.git

web: Update docstrings for prepare and on_finish

Document the fact that sometimes prepare() is not called, even if
initialize() and on_finish() are.

Updates #3430
Closes #3431
---

diff --git a/tornado/web.py b/tornado/web.py
index 289c6738..0303f547 100644
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -284,7 +284,8 @@ class RequestHandler:
         """Called at the beginning of a request before  `get`/`post`/etc.
 
         Override this method to perform common initialization regardless
-        of the request method.
+        of the request method. There is no guarantee that ``prepare`` will
+        be called if an error occurs that is handled by the framework.
 
         Asynchronous support: Use ``async def`` or decorate this method with
         `.gen.coroutine` to make it asynchronous.
@@ -299,10 +300,14 @@ class RequestHandler:
     def on_finish(self) -> None:
         """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.
+        Override this method to perform cleanup, logging, etc. This method is primarily intended as
+        a counterpart to `prepare`. However, there are a few error cases where ``on_finish`` may be
+        called when ``prepare`` has not. (These are considered bugs and may be fixed in the future,
+        but for now you may need to check to see if the initialization work done in ``prepare`` has
+        occurred)
+
+        ``on_finish`` may not produce any output, as it is called after the response has been sent
+        to the client.
         """
         pass