From: Bartosz Sławecki <bartosz@ilikepython.com>
Date: Mon, 26 Jan 2026 15:50:27 +0000 (+0100)
Subject: gh-142119: Clarify context manager protocol documentation on `ContextVar.set` and... 
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=04d497c284ac933488cc747b3f7082beab300848;p=thirdparty%2FPython%2Fcpython.git

gh-142119: Clarify context manager protocol documentation on `ContextVar.set` and `Token` (GH-143694)
---

diff --git a/Doc/library/contextvars.rst b/Doc/library/contextvars.rst
index b218468a084d..60376e730cb1 100644
--- a/Doc/library/contextvars.rst
+++ b/Doc/library/contextvars.rst
@@ -77,6 +77,32 @@ Context Variables
       to restore the variable to its previous value via the
       :meth:`ContextVar.reset` method.
 
+      For convenience, the token object can be used as a context manager
+      to avoid calling :meth:`ContextVar.reset` manually::
+
+          var = ContextVar('var', default='default value')
+
+          with var.set('new value'):
+              assert var.get() == 'new value'
+
+          assert var.get() == 'default value'
+
+      It is a shorthand for::
+
+          var = ContextVar('var', default='default value')
+
+          token = var.set('new value')
+          try:
+              assert var.get() == 'new value'
+          finally:
+              var.reset(token)
+
+          assert var.get() == 'default value'
+
+      .. versionadded:: 3.14
+
+         Added support for using tokens as context managers.
+
    .. method:: reset(token)
 
       Reset the context variable to the value it had before the
@@ -101,16 +127,8 @@ Context Variables
    the value of the variable to what it was before the corresponding
    *set*.
 
-   The token supports :ref:`context manager protocol <context-managers>`
-   to restore the corresponding context variable value at the exit from
-   :keyword:`with` block::
-
-       var = ContextVar('var', default='default value')
-
-       with var.set('new value'):
-           assert var.get() == 'new value'
-
-       assert var.get() == 'default value'
+   Tokens support the :ref:`context manager protocol <context-managers>`
+   to automatically reset context variables. See :meth:`ContextVar.set`.
 
    .. versionadded:: 3.14