From a67f1e233476729f2608441997b8ef24ab29e9e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= <bartosz@ilikepython.com>
Date: Mon, 26 Jan 2026 16:50:27 +0100
Subject: [PATCH] gh-142119: Clarify context manager protocol documentation on
 `ContextVar.set` and `Token` (GH-143694) (cherry picked from commit
 04d497c284ac933488cc747b3f7082beab300848)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>
---
 Doc/library/contextvars.rst | 38 +++++++++++++++++++++++++++----------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/Doc/library/contextvars.rst b/Doc/library/contextvars.rst
index 57580ce026e96a..043a8d9d9205bd 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