update docs about contexts

docs/api.rst

@@ -311,56 +311,28 @@ Useful Internals
 .. autoclass:: flask.ctx.RequestContext
    :members:
 
-.. data:: _request_ctx_stack
+.. data:: flask.globals.request_ctx
 
-    The internal :class:`~werkzeug.local.LocalStack` that holds
-    :class:`~flask.ctx.RequestContext` instances. Typically, the
-    :data:`request` and :data:`session` proxies should be accessed
-    instead of the stack. It may be useful to access the stack in
-    extension code.
+    The current :class:`~flask.ctx.RequestContext`. If a request context
+    is not active, accessing attributes on this proxy will raise a
+    ``RuntimeError``.
 
-    The following attributes are always present on each layer of the
-    stack:
-
-    `app`
-      the active Flask application.
-
-    `url_adapter`
-      the URL adapter that was used to match the request.
-
-    `request`
-      the current request object.
-
-    `session`
-      the active session object.
-
-    `g`
-      an object with all the attributes of the :data:`flask.g` object.
-
-    `flashes`
-      an internal cache for the flashed messages.
-
-    Example usage::
-
-        from flask import _request_ctx_stack
-
-        def get_session():
-            ctx = _request_ctx_stack.top
-            if ctx is not None:
-                return ctx.session
+    This is an internal object that is essential to how Flask handles
+    requests. Accessing this should not be needed in most cases. Most
+    likely you want :data:`request` and :data:`session` instead.
 
 .. autoclass:: flask.ctx.AppContext
    :members:
 
-.. data:: _app_ctx_stack
+.. data:: flask.globals.app_ctx
 
-    The internal :class:`~werkzeug.local.LocalStack` that holds
-    :class:`~flask.ctx.AppContext` instances. Typically, the
-    :data:`current_app` and :data:`g` proxies should be accessed instead
-    of the stack. Extensions can access the contexts on the stack as a
-    namespace to store data.
+    The current :class:`~flask.ctx.AppContext`. If an app context is not
+    active, accessing attributes on this proxy will raise a
+    ``RuntimeError``.
 
-    .. versionadded:: 0.9
+    This is an internal object that is essential to how Flask handles
+    requests. Accessing this should not be needed in most cases. Most
+    likely you want :data:`current_app` and :data:`g` instead.
 
 .. autoclass:: flask.blueprints.BlueprintSetupState
    :members:

docs/appcontext.rst

@@ -136,14 +136,6 @@ local from ``get_db()``::
 Accessing ``db`` will call ``get_db`` internally, in the same way that
 :data:`current_app` works.
 
-----
-
-If you're writing an extension, :data:`g` should be reserved for user
-code. You may store internal data on the context itself, but be sure to
-use a sufficiently unique name. The current context is accessed with
-:data:`_app_ctx_stack.top <_app_ctx_stack>`. For more information see
-:doc:`/extensiondev`.
-
 
 Events and Signals
 ------------------

docs/extensiondev.rst

@@ -187,12 +187,6 @@ when the application context ends. If it should only be valid during a
 request, or would not be used in the CLI outside a reqeust, use
 :meth:`~flask.Flask.teardown_request`.
 
-An older technique for storing context data was to store it on
-``_app_ctx_stack.top`` or ``_request_ctx_stack.top``. However, this just
-moves the same namespace collision problem elsewhere (although less
-likely) and modifies objects that are very internal to Flask's
-operations. Prefer storing data under a unique name in ``g``.
-
 
 Views and Models
 ----------------

docs/patterns/sqlite3.rst

@@ -30,10 +30,6 @@ or create an application context itself.  At that point the ``get_db``
 function can be used to get the current database connection.  Whenever the
 context is destroyed the database connection will be terminated.
 
-Note: if you use Flask 0.9 or older you need to use
-``flask._app_ctx_stack.top`` instead of ``g`` as the :data:`flask.g`
-object was bound to the request and not application context.
-
 Example::
 
     @app.route('/')

docs/reqcontext.rst

@@ -37,12 +37,14 @@ context, which also pushes an :doc:`app context </appcontext>`. When the
 request ends it pops the request context then the application context.
 
 The context is unique to each thread (or other worker type).
-:data:`request` cannot be passed to another thread, the other thread
-will have a different context stack and will not know about the request
-the parent thread was pointing to.
+:data:`request` cannot be passed to another thread, the other thread has
+a different context space and will not know about the request the parent
+thread was pointing to.
 
-Context locals are implemented in Werkzeug. See :doc:`werkzeug:local`
-for more information on how this works internally.
+Context locals are implemented using Python's :mod:`contextvars` and
+Werkzeug's :class:`~werkzeug.local.LocalProxy`. Python manages the
+lifetime of context vars automatically, and local proxy wraps that
+low-level interface to make the data easier to work with.
 
 
 Manually Push a Context
@@ -87,10 +89,9 @@ How the Context Works
 
 The :meth:`Flask.wsgi_app` method is called to handle each request. It
 manages the contexts during the request. Internally, the request and
-application contexts work as stacks, :data:`_request_ctx_stack` and
-:data:`_app_ctx_stack`. When contexts are pushed onto the stack, the
+application contexts work like stacks. When contexts are pushed, the
 proxies that depend on them are available and point at information from
-the top context on the stack.
+the top item.
 
 When the request starts, a :class:`~ctx.RequestContext` is created and
 pushed, which creates and pushes an :class:`~ctx.AppContext` first if
@@ -99,10 +100,10 @@ these contexts are pushed, the :data:`current_app`, :data:`g`,
 :data:`request`, and :data:`session` proxies are available to the
 original thread handling the request.
 
-Because the contexts are stacks, other contexts may be pushed to change
-the proxies during a request. While this is not a common pattern, it
-can be used in advanced applications to, for example, do internal
-redirects or chain different applications together.
+Other contexts may be pushed to change the proxies during a request.
+While this is not a common pattern, it can be used in advanced
+applications to, for example, do internal redirects or chain different
+applications together.
 
 After the request is dispatched and a response is generated and sent,
 the request context is popped, which then pops the application context.