--- /home/ncoghlan/devel/contextlib2/../cpython/Doc/library/contextlib.rst 2024-05-20 12:53:59.936907756 +1000 +++ /home/ncoghlan/devel/contextlib2/docs/contextlib2.rst 2024-05-23 16:52:15.696031500 +1000 @@ -1,20 +1,5 @@ -:mod:`!contextlib` --- Utilities for :keyword:`!with`\ -statement contexts -========================================================================== - -.. module:: contextlib - :synopsis: Utilities for with-statement contexts. - -**Source code:** :source:`Lib/contextlib.py` - --------------- - -This module provides utilities for common tasks involving the :keyword:`with` -statement. For more information see also :ref:`typecontextmanager` and -:ref:`context-managers`. - - -Utilities ---------- +API Reference +------------- Functions and classes provided: @@ -26,8 +11,8 @@ ``self`` while :meth:`object.__exit__` is an abstract method which by default returns ``None``. See also the definition of :ref:`typecontextmanager`. - .. versionadded:: 3.6 - + .. versionadded:: 0.6.0 + Part of the standard library in Python 3.6 and later .. class:: AbstractAsyncContextManager @@ -38,8 +23,8 @@ returns ``None``. See also the definition of :ref:`async-context-managers`. - .. versionadded:: 3.7 - + .. versionadded:: 21.6.0 + Part of the standard library in Python 3.7 and later .. decorator:: contextmanager @@ -95,9 +80,6 @@ created by :func:`contextmanager` to meet the requirement that context managers support multiple invocations in order to be used as decorators). - .. versionchanged:: 3.2 - Use of :class:`ContextDecorator`. - .. decorator:: asynccontextmanager @@ -126,7 +108,10 @@ async with get_connection() as conn: return conn.query('SELECT ...') - .. versionadded:: 3.7 + .. versionadded:: 21.6.0 + Part of the standard library in Python 3.7 and later, enhanced in + Python 3.10 and later to allow created async context managers to be used + as async function decorators. Context managers defined with :func:`asynccontextmanager` can be used either as decorators or with :keyword:`async with` statements:: @@ -151,10 +136,6 @@ created by :func:`asynccontextmanager` to meet the requirement that context managers support multiple invocations in order to be used as decorators. - .. versionchanged:: 3.10 - Async context managers created with :func:`asynccontextmanager` can - be used as decorators. - .. function:: closing(thing) @@ -221,7 +202,8 @@ variables work as expected, and the exit code isn't run after the lifetime of some task it depends on). - .. versionadded:: 3.10 + .. versionadded:: 21.6.0 + Part of the standard library in Python 3.10 and later .. _simplifying-support-for-single-optional-context-managers: @@ -269,11 +251,11 @@ async with cm as session: # Send http requests with session - .. versionadded:: 3.7 - - .. versionchanged:: 3.10 - :term:`asynchronous context manager` support was added. + .. versionadded:: 0.6.0 + Part of the standard library in Python 3.7 and later + .. versionchanged:: 21.6.0 + Updated to Python 3.10 version with :term:`asynchronous context manager` support .. function:: suppress(*exceptions) @@ -314,13 +296,15 @@ If the code within the :keyword:`!with` block raises a :exc:`BaseExceptionGroup`, suppressed exceptions are removed from the - group. If any exceptions in the group are not suppressed, a group containing them is re-raised. + group. If any exceptions in the group are not suppressed, a group containing + them is re-raised. - .. versionadded:: 3.4 + .. versionadded:: 0.5 + Part of the standard library in Python 3.4 and later - .. versionchanged:: 3.12 - ``suppress`` now supports suppressing exceptions raised as - part of an :exc:`BaseExceptionGroup`. + .. versionchanged:: 24.6.0 + Updated to Python 3.12 version that supports suppressing exceptions raised + as part of a :exc:`BaseExceptionGroup`. .. function:: redirect_stdout(new_target) @@ -359,7 +343,8 @@ This context manager is :ref:`reentrant `. - .. versionadded:: 3.4 + .. versionadded:: 0.5 + Part of the standard library in Python 3.4 and later .. function:: redirect_stderr(new_target) @@ -369,7 +354,8 @@ This context manager is :ref:`reentrant `. - .. versionadded:: 3.5 + .. versionadded:: 0.5 + Part of the standard library in Python 3.5 and later .. function:: chdir(path) @@ -386,7 +372,8 @@ This context manager is :ref:`reentrant `. - .. versionadded:: 3.11 + .. versionadded:: 24.6.0 + Part of the standard library in Python 3.11 and later .. class:: ContextDecorator() @@ -464,8 +451,6 @@ statements. If this is not the case, then the original construct with the explicit :keyword:`!with` statement inside the function should be used. - .. versionadded:: 3.2 - .. class:: AsyncContextDecorator @@ -505,7 +490,8 @@ The bit in the middle Finishing - .. versionadded:: 3.10 + .. versionadded:: 21.6.0 + Part of the standard library in Python 3.10 and later .. class:: ExitStack() @@ -547,7 +533,8 @@ foundation for higher level context managers that manipulate the exit stack in application specific ways. - .. versionadded:: 3.3 + .. versionadded:: 0.4 + Part of the standard library in Python 3.3 and later .. method:: enter_context(cm) @@ -558,9 +545,10 @@ These context managers may suppress exceptions just as they normally would if used directly as part of a :keyword:`with` statement. - .. versionchanged:: 3.11 - Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm* - is not a context manager. + .. versionchanged:: 24.6.0 + When running on Python 3.11 or later, raises :exc:`TypeError` instead + of :exc:`AttributeError` if *cm* is not a context manager. This aligns + with the behaviour of :keyword:`with` statements in Python 3.11+. .. method:: push(exit) @@ -632,9 +620,10 @@ Similar to :meth:`ExitStack.enter_context` but expects an asynchronous context manager. - .. versionchanged:: 3.11 - Raises :exc:`TypeError` instead of :exc:`AttributeError` if *cm* - is not an asynchronous context manager. + .. versionchanged:: 24.6.0 + When running on Python 3.11 or later, raises :exc:`TypeError` instead + of :exc:`AttributeError` if *cm* is not an asynchronous context manager. + This aligns with the behaviour of ``async with`` statements in Python 3.11+. .. method:: push_async_exit(exit) @@ -658,7 +647,9 @@ # the async with statement, even if attempts to open a connection # later in the list raise an exception. - .. versionadded:: 3.7 + .. versionadded:: 21.6.0 + Part of the standard library in Python 3.7 and later + Examples and Recipes --------------------