Merge pull request #4318 from eprigorodov/patch-1

document session object lifetime

src/flask/sessions.py

@@ -131,6 +131,13 @@ class SessionInterface:
         app = Flask(__name__)
         app.session_interface = MySessionInterface()
 
+    Multiple requests with the same session may be sent and handled
+    concurrently. When implementing a new session interface, consider
+    whether reads or writes to the backing store must be synchronized.
+    There is no guarantee on the order in which the session for each
+    request is opened or saved, it will occur in the order that requests
+    begin and end processing.
+
     .. versionadded:: 0.8
     """
 
@@ -292,20 +299,25 @@ class SessionInterface:
     def open_session(
         self, app: "Flask", request: "Request"
     ) -> t.Optional[SessionMixin]:
-        """This method has to be implemented and must either return ``None``
+        """This is called at the beginning of each request, after
-        in case the loading failed because of a configuration error or an
+        pushing the request context, before matching the URL.
-        instance of a session object which implements a dictionary like
+
-        interface + the methods and attributes on :class:`SessionMixin`.
+        This must return an object which implements a dictionary-like
+        interface as well as the :class:`SessionMixin` interface.
+
+        This will return ``None`` to indicate that loading failed in
+        some way that is not immediately an error. The request
+        context will fall back to using :meth:`make_null_session`
+        in this case.
         """
         raise NotImplementedError()
 
     def save_session(
         self, app: "Flask", session: SessionMixin, response: "Response"
     ) -> None:
-        """This is called for actual sessions returned by :meth:`open_session`
+        """This is called at the end of each request, after generating
-        at the end of the request.  This is still called during a request
+        a response, before removing the request context. It is skipped
-        context so if you absolutely need access to the request you can do
+        if :meth:`is_null_session` returns ``True``.
-        that.
         """
         raise NotImplementedError()