https://github.com/python/cpython/commit/9be2290016ed9e63a17f2be24086348ab4450fb5 commit: 9be2290016ed9e63a17f2be24086348ab4450fb5 branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: encukou <[email protected]> date: 2026-01-26T15:56:19Z summary:
[3.14] gh-142119: Clarify context manager protocol documentation on `ContextVar.set` and `Token` (GH-143694) (GH-144251) (cherry picked from commit 04d497c284ac933488cc747b3f7082beab300848) Co-authored-by: Bartosz Sławecki <[email protected]> files: M Doc/library/contextvars.rst 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 _______________________________________________ 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]
