https://github.com/python/cpython/commit/04d497c284ac933488cc747b3f7082beab300848
commit: 04d497c284ac933488cc747b3f7082beab300848
branch: main
author: Bartosz Sławecki <[email protected]>
committer: encukou <[email protected]>
date: 2026-01-26T16:50:27+01:00
summary:
gh-142119: Clarify context manager protocol documentation on `ContextVar.set`
and `Token` (GH-143694)
files:
M Doc/library/contextvars.rst
diff --git a/Doc/library/contextvars.rst b/Doc/library/contextvars.rst
index b218468a084db1..60376e730cb102 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
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
