cpython: 7343730185a3 (original) (raw)

Mercurial > cpython

changeset 73983:7343730185a3

Issue #13597: Improve documentation of standard streams. [#13597]

line wrap: on

line diff

--- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -941,31 +941,42 @@ always available. stdout stderr

• :term:File objects <file object> corresponding to the interpreter's standard
• input, output and error streams. stdin is used for all interpreter input
• except for scripts but including calls to :func:input. stdout is used
• for the output of :func:print and :term:expression statements and for the
• prompts of :func:input. The interpreter's own prompts
• and (almost all of) its error messages go to stderr. stdout and
• stderr needn't be built-in file objects: any object is acceptable as long
• as it has a :meth:write method that takes a string argument. (Changing these
• objects doesn't affect the standard I/O streams of processes executed by
• :func:os.popen, :func:os.system or the :func:exec\* family of functions in
• the :mod:os module.)

• :term:File objects <file object> used by the interpreter for standard
• input, output and errors: +
• • stdin is used for all interactive input (including calls to

• :func:`input`);[](#l1.22)

• • stdout is used for the output of :func:print and :term:expression

• statements and for the prompts of :func:`input`;[](#l1.24)

• • The interpreter's own prompts and its error messages go to stderr. +
• By default, these streams are regular text streams as returned by the
• :func:open function. Their parameters are chosen as follows:

• The standard streams are in text mode by default. To write or read binary
• data to these, use the underlying binary buffer. For example, to write bytes
• to :data:stdout, use sys.stdout.buffer.write(b'abc'). Using
• :meth:io.TextIOBase.detach streams can be made binary by default. This

• • The character encoding is platform-dependent. Under Windows, if the stream

• is interactive (that is, if its :meth:`isatty` method returns True), the[](#l1.35)

• console codepage is used, otherwise the ANSI code page.  Under other[](#l1.36)

• platforms, the locale encoding is used (see :meth:`locale.getpreferredencoding`).[](#l1.37)

+

• Under all platforms though, you can override this value by setting the[](#l1.39)

• :envvar:`PYTHONIOENCODING` environment variable.[](#l1.40)

+

• • When interactive, standard streams are line-buffered. Otherwise, they

• are block-buffered like regular text files.  You can override this[](#l1.43)

• value with the :option:`-u` command-line option.[](#l1.44)

+

• To write or read binary data from/to the standard streams, use the
• underlying binary :data:~io.TextIOBase.buffer. For example, to write
• bytes to :data:stdout, use sys.stdout.buffer.write(b'abc'). Using
• :meth:io.TextIOBase.detach, streams can be made binary by default. This function sets :data:stdin and :data:stdout to binary:: def make_streams_binary(): sys.stdin = sys.stdin.detach() sys.stdout = sys.stdout.detach()

• Note that the streams can be replaced with objects (like
• :class:io.StringIO) that do not support the
• :attr:~io.BufferedIOBase.buffer attribute or the

• Note that the streams may be replaced with objects (like :class:io.StringIO)
• that do not support the :attr:~io.BufferedIOBase.buffer attribute or the :meth:~io.BufferedIOBase.detach method and can raise :exc:AttributeError or :exc:io.UnsupportedOperation.