mirror of
https://github.com/jazzband/contextlib2.git
synced 2026-03-18 22:50:24 +00:00
225 lines
7 KiB
Diff
225 lines
7 KiB
Diff
--- /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 <reentrant-cms>`.
|
|
|
|
- .. 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 <reentrant-cms>`.
|
|
|
|
- .. 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 <reentrant-cms>`.
|
|
|
|
- .. 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
|
|
--------------------
|