From 485415ec9c72adbfac591ce352de2976a4b7d804 Mon Sep 17 00:00:00 2001 From: Cody Maloney Date: Thu, 2 Oct 2025 01:47:26 -0700 Subject: [PATCH 1/4] gh-139452: Clarify redirect_stdout, stderr behavior These don't "redirect" like a terminal where typically the file pointed to by fd 1 and 2 are made the "same" by the preparing process (ex. by `dup2` the given fd into that specific fd number). Rather, these context managers set the respective globals to the provided value. In most cases that should be a "file object". --- Doc/library/contextlib.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 176be4ff333955..7d0e6b8d8dddb2 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -327,10 +327,12 @@ Functions and classes provided: .. function:: redirect_stdout(new_target) Context manager for temporarily redirecting :data:`sys.stdout` to - another file or file-like object. + another :term:`file object`. This tool adds flexibility to existing functions or classes whose output - is hardwired to stdout. + is hardwired to :data:`sys.stdout`. This does not modify underlying file + objects or file descriptors. It sets the global :data:`sys.stdout` to the + provided value and at context exit sets it to the previous value. For example, the output of :func:`help` normally is sent to *sys.stdout*. You can capture that output in a string by redirecting the output to an @@ -366,8 +368,9 @@ Functions and classes provided: .. function:: redirect_stderr(new_target) - Similar to :func:`~contextlib.redirect_stdout` but redirecting - :data:`sys.stderr` to another file or file-like object. + Similar to :func:`~contextlib.redirect_stdout` but redirecting the global + :data:`sys.stderr` to another value, typically a :term:`file object` + returned from :func:`open`. This context manager is :ref:`reentrant `. From af01958a3f7c08a04593701221f1bf9e645ea280 Mon Sep 17 00:00:00 2001 From: Cody Maloney Date: Thu, 2 Oct 2025 18:28:58 -0700 Subject: [PATCH 2/4] Add discard/suppress example --- Doc/library/contextlib.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 7d0e6b8d8dddb2..165df36acb5d30 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -356,6 +356,12 @@ Functions and classes provided: with redirect_stdout(sys.stderr): help(pow) + To discard or suppress the output of :func:`help` without collecting the data:: + + with open(os.devnull, 'w') as devnull: + with redirect_stdout(devnull): + help(pow) + Note that the global side effect on :data:`sys.stdout` means that this context manager is not suitable for use in library code and most threaded applications. It also has no effect on the output of subprocesses. From 976045e084f44c6c0a389b3b149b43c57cc303fb Mon Sep 17 00:00:00 2001 From: Cody Maloney Date: Mon, 6 Oct 2025 00:51:50 -0700 Subject: [PATCH 3/4] Remove open() reference per issue comment --- Doc/library/contextlib.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 165df36acb5d30..7638808dc0e33e 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -375,8 +375,7 @@ Functions and classes provided: .. function:: redirect_stderr(new_target) Similar to :func:`~contextlib.redirect_stdout` but redirecting the global - :data:`sys.stderr` to another value, typically a :term:`file object` - returned from :func:`open`. + :data:`sys.stderr` to another value, typically a :term:`file object`. This context manager is :ref:`reentrant `. From 40df344c7acd624aa54d072033d92eb1562e399e Mon Sep 17 00:00:00 2001 From: Cody Maloney Date: Tue, 7 Oct 2025 17:02:26 -0700 Subject: [PATCH 4/4] Update per review comments --- Doc/library/contextlib.rst | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 7638808dc0e33e..d0fa645093a3e9 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -330,9 +330,7 @@ Functions and classes provided: another :term:`file object`. This tool adds flexibility to existing functions or classes whose output - is hardwired to :data:`sys.stdout`. This does not modify underlying file - objects or file descriptors. It sets the global :data:`sys.stdout` to the - provided value and at context exit sets it to the previous value. + is hardwired to :data:`sys.stdout`. For example, the output of :func:`help` normally is sent to *sys.stdout*. You can capture that output in a string by redirecting the output to an @@ -356,12 +354,6 @@ Functions and classes provided: with redirect_stdout(sys.stderr): help(pow) - To discard or suppress the output of :func:`help` without collecting the data:: - - with open(os.devnull, 'w') as devnull: - with redirect_stdout(devnull): - help(pow) - Note that the global side effect on :data:`sys.stdout` means that this context manager is not suitable for use in library code and most threaded applications. It also has no effect on the output of subprocesses. @@ -375,7 +367,7 @@ Functions and classes provided: .. function:: redirect_stderr(new_target) Similar to :func:`~contextlib.redirect_stdout` but redirecting the global - :data:`sys.stderr` to another value, typically a :term:`file object`. + :data:`sys.stderr` to another :term:`file object`. This context manager is :ref:`reentrant `.