From cccb2d909cdb6f3a730bf7d0b6719d0188421770 Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Mon, 28 Apr 2025 15:44:21 -0400 Subject: [PATCH] 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 --- tornado/web.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) 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 -- 2.47.2