Index: Doc/library/sys.rst =================================================================== --- Doc/library/sys.rst (revision 87918) +++ Doc/library/sys.rst (working copy) @@ -936,7 +936,16 @@ :meth:`~io.BufferedIOBase.detach` method and can raise :exc:`AttributeError` or :exc:`io.UnsupportedOperation`. + .. note:: + On Windows since Python XXX, the initial standard streams support input + or output of all Unicode characters when they are attached to a console. + See :class:`io.TextIOWrapper` for further details about this support. + For Unicode characters to be displayed and input correctly when Python + is run from a Command Prompt, its font must be set to Lucida Console or + Consolas. + + .. data:: __stdin__ __stdout__ __stderr__ Index: Doc/library/os.rst =================================================================== --- Doc/library/os.rst (revision 87918) +++ Doc/library/os.rst (working copy) @@ -595,7 +595,15 @@ Return a string describing the encoding of the device associated with *fd* if it is connected to a terminal; else return :const:`None`. + .. note:: + On Windows, when *fd* is associated with a console, it is possible to + use ``t = io.TextIOWrapper(io.open(fd, ...)); t.use_console = True`` to + create a text stream object that can read and/or write all Unicode characters, + even though ``device_encoding(fd)`` may return an encoding that does not + support all of Unicode. + + .. function:: dup(fd) Return a duplicate of file descriptor *fd*. @@ -609,7 +617,23 @@ Availability: Unix, Windows. + .. note:: + On Windows, if a :class:`io.TextIOWrapper` object on which :attr:`use_console` + has been set to ``True`` is wrapping a buffer with the file descriptor + given by *fd2*, then the :meth:`redirect` method of the + :class:`TextIOWrapper` needs to be called for it to remain associated + with the correct console or stream. If *fd2* is 0, 1, or 2, then + :func:`os.dup2` will automatically call :meth:`redirect` on + :data:`sys.__stdin__`, :data:`sys.__stdout__`, or :data:`sys.__stderr__` + respectively. It will *also* call :meth:`redirect` on + :data:`sys.stdin`, :data:`sys.stdout`, or :data:`sys.stderr` if it + has been changed to a different object that has a :meth:`redirect` method. + + To avoid this automatic calling of :meth:`redirect` methods, use + ``getattr(os, '_dup2', os.dup2)(fd, fd2)``. + + .. function:: fchmod(fd, mode) Change the mode of the file given by *fd* to the numeric *mode*. See the docs Index: Doc/library/io.rst =================================================================== --- Doc/library/io.rst (revision 87918) +++ Doc/library/io.rst (working copy) @@ -705,14 +705,36 @@ Write the string *s* to the stream and return the number of characters written. + .. method:: redirect() + For a console text stream, ensure that the console handle is up-to-date + after a possible redirection of the underlying file descriptor. If this + is not a console text stream, or on platforms other than Windows, this + method has no effect. + + The underlying fd is found by calling ``fileno()`` on this stream's + buffer object. If the buffer no longer has a :meth:`fileno` method or + if ``buffer.fileno()`` is no longer associated with a console, then + the stream switches to using the *buffer*, *encoding* and *errors* mode + passed to the constructor. + + Since the :class:`TextIOWrapper` interface in versions of Python prior + to XXX did not have a :meth:`redirect` method, you should check whether + this method exists before calling it, e.g.:: + + if hasattr(textio, 'redirect'): + textio.redirect() + + .. class:: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False) A buffered text stream over a :class:`BufferedIOBase` binary stream. It inherits :class:`TextIOBase`. *encoding* gives the name of the encoding that the stream will be decoded or - encoded with. It defaults to :func:`locale.getpreferredencoding`. + encoded with. It defaults to ``os.device_encoding(buffer.fileno())`` if + *buffer* has a :meth:`fileno` method and its file descriptor is attached + to a terminal, or ``locale.getpreferredencoding()`` otherwise. *errors* is an optional string that specifies how encoding and decoding errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError` @@ -737,14 +759,54 @@ If *line_buffering* is ``True``, :meth:`flush` is implied when a call to write contains a newline character. - :class:`TextIOWrapper` provides one attribute in addition to those of - :class:`TextIOBase` and its parents: + :class:`TextIOWrapper` provides the following attributes in addition to + those of :class:`TextIOBase` and its parents: .. attribute:: line_buffering Whether line buffering is enabled. + .. attribute:: use_console + Setting this attribute only has an effect in versions of Python since + XXX running on Windows. + + In that case, setting :attr:`use_console` to ``True`` for a + :class`TextIOWrapper` object that is connected to a Windows console + allows it to directly use Unicode console APIs, ignoring the *encoding* + and *errors* mode passed to the constructor. This enables use of + the full Unicode character set even though the encoding may only + support a subset of Unicode. + + :attr:`use_console` is set by default for the initial stdin, stdout + and stderr streams on Windows. It is not set by default for other + streams, primarily because that could cause compatibility problems + due to the console APIs bypassing the underlying buffer object. + Setting :attr:`use_console` may also change buffering behavior. + + Setting :attr:`use_console` to ``False`` prevents Unicode console + APIs from being used when they otherwise would be. + + (This is an attribute rather than a parameter to the constructor, + so that ``t.use_console = True`` will be silently ignored on versions + of Python prior to XXX, which is usually the desired behavior.) + + .. note:: + + Setting :attr:`use_console` to ``True`` on streams that are not + connected to a console has no effect, so it does not prevent the + stream from being redirected. However, if a :class:`TextIOWrapper` + object is initially connected to a console and then + ``os.dup2(fd, fd2)`` is used to redirect the underlying + file descriptor (``fd2``), the :class:`TextIOWrapper` might + continue to access the original console. To avoid this problem, + call the :meth:`redirect` method after calling :func:`os.dup2`. + It is unnecessary for do this for :data:`sys.stdin`, :data:`stdout` + and :data:`stderr`, or for :data:`sys.__stdin__`, :data:`__stdout__` + and :data:`__stderr__`, since :func:`os.dup2` will do so + automatically when redirecting the standard I/O file descriptors. + + .. class:: StringIO(initial_value='', newline=None) An in-memory stream for text I/O.