[New-bugs-announce] [issue40868] io.TextIOBase.buffer is not necessarily a buffer

[Manuel Jacob]

New submission from Manuel Jacob <me at manueljacob.de>:

https://docs.python.org/dev/library/io.html#io.TextIOBase.buffer says:

"The underlying binary buffer (a BufferedIOBase instance) that TextIOBase deals with. This is not part of the TextIOBase API and may not exist in some implementations."

It is not necessarily a buffer (a BufferedIOBase instance), e.g. when the stdout and stderr streams are set to be unbuffered. Example:

% python -u
Python 3.8.3 (default, May 17 2020, 18:15:42) 
[GCC 10.1.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import io, sys
>>> sys.stdout
<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>
>>> isinstance(sys.stdout, io.TextIOBase)
True
>>> sys.stdout.buffer
<_io.FileIO name='<stdout>' mode='wb' closefd=False>
>>> isinstance(sys.stdout.buffer, io.BufferedIOBase)
False

Therefore the name and the documentation are incorrect.

I suggest to deprecate the attribute "buffer", introduce a new attribute with a correct name, and forward the old attribute to the new attribute and vice versa in the io.TextIOBase class.

I think that "binary" would be a good attribute name for the underlying binary stream, as it would be consistent with io.BufferedIOBase.raw (for "the underlying raw stream").

----------
assignee: docs at python
components: Documentation, IO
messages: 370744
nosy: docs at python, mjacob
priority: normal
severity: normal
status: open
title: io.TextIOBase.buffer is not necessarily a buffer

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40868>
_______________________________________