Doc: improve documentation for `contextlib.redirect_stderr()`

[wolfgang-eder]

Bug report

Bug description:

import contextlib
import sys

print('to stdout', file=sys.stdout)
print('to stderr', file=sys.stderr)
with contextlib.redirect_stdout(None):
    print('to stdout, stdout suppressed', file=sys.stdout)
    print('to stderr, stdout suppressed', file=sys.stderr)
with contextlib.redirect_stderr(None):
    print('to stdout, stderr suppressed', file=sys.stdout)
    print('to stderr, stderr suppressed', file=sys.stderr)
print('to stdout', file=sys.stdout)
print('to stderr', file=sys.stderr)

This prints:

to stdout
to stderr
to stderr, stdout suppressed
to stdout, stderr suppressed
to stderr, stderr suppressed
to stdout
to stderr

The line "to stderr, stderr suppressed" should be suppressed.

CPython versions tested on:

3.12

Operating systems tested on:

Linux

Linked PRs

• gh-139452: Clarify redirect_stdout, stderr behavior #139490

[wolfgang-eder]

Using strace, I observe the following:

write(1, "to stdout\n", 10to stdout
)             = 10
write(2, "to stderr\n", 10to stderr
)             = 10
write(2, "to stderr, stdout suppressed\n", 29to stderr, stdout suppressed
) = 29
write(1, "to stdout, stderr suppressed\n", 29to stdout, stderr suppressed
) = 29
write(1, "to stderr, stderr suppressed\n", 29to stderr, stderr suppressed
) = 29
write(1, "to stdout\n", 10to stdout
)             = 10
write(2, "to stderr\n", 10to stderr
)             = 10

It looks like while in redirect_stderr(None), printing to sys.stderr actually goes to fh 1 (sys.stdout)

[wolfgang-eder]

I updated my test program:

import contextlib
import sys

print('to stdout', file=sys.stdout)
print('to stderr', file=sys.stderr)
print(sys.stdout)
print(sys.stderr)
with contextlib.redirect_stdout(None):
    print('to stdout, stdout suppressed', file=sys.stdout)
    print('to stderr, stdout suppressed', file=sys.stderr)
    print(sys.stdout, file=sys.stderr)
    print(sys.stderr, file=sys.stderr)
with contextlib.redirect_stderr(None):
    print('to stdout, stderr suppressed', file=sys.stdout)
    print('to stderr, stderr suppressed', file=sys.stderr)
    print(sys.stdout, file=sys.stderr)
    print(sys.stderr, file=sys.stderr)
print('to stdout', file=sys.stdout)
print('to stderr', file=sys.stderr)
print(sys.stdout)
print(sys.stderr)

I can see now that sys.stdout and sys.stderr become None when they are redirected.
Alas, calling print with file=None prints on stdout.
So I understand what happens now.
I'd appreciate if you could update the documentation for redirect_stderr
and explain how it affects print('...', file=sys.stderr) in this non-intuitive way.
Thanks

[StanFromIreland]

This is because of how print works, for example:

>>> print("hello stdout", file=None)
hello stdout
>>> sys.stdout = None
>>> print("hello stdout", file=sys.stdout)
>>> 

If file is None, it prints to sys.stdout.

[wolfgang-eder]

Thanks Stan
As a note, this is how I do it now:

with open(os.devnull, 'w') as devnull:
    with contextlib.redirect_stderr(devnull):

Do you agree that documentation should be updated?
If not, we can close this ticket.
Thanks again, Wolfgang

[StanFromIreland]

I can see now that sys.stdout and sys.stderr become None when they are redirected. Alas, calling print with file=None prints on stdout.

Ah, I had not noticed you just replied!

I'd appreciate if you could update the documentation for redirect_stderr and explain how it affects print('...', file=sys.stderr) in this non-intuitive way.

I don't know, I assume there are many more such confusing cases, so I don't think this should be in the docs for contextlib. It would make sense in a tutorial, but this is more something for help sites and the like IMO. We can see what others think.

[cmaloney]

The docs for redirect_stdout currently has a line which I think covers this (None is not a file-like object)

Context manager for temporarily redirecting :data:sys.stdout to another file or file-like object.

My brain finds the "redirect" part of that a little ambiguous as it makes me think of terminal redirection which tends to be using the same integer fd and/or dup to make things point to the same logical file/stream. redirect_stdout just sets the global sys.stdout to an arbitrary value (undoing it on __exit__ of the context manager).

I actually like that redirect_stdout is really duck-typing in this case. The behavior combo with print() is definitely surprising but in testing I can see where setting sys.stdout to None or other arbitrary value may be useful.

I think a small update to make "file-like object" link to the glossary term "file object" + maybe mention open to get one would be good. Working on a PR for that; experimenting to try and find good ways to say "this is not terminal redirection"; changing the first line to "set :data:sys.stdout" instead of redirect doesn't feel right to me given the function is redirect_stdout.