io.TextIOBase.buffer is not necessarily a buffer

@manueljacob

BPO	40868
Nosy	@manueljacob

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-06-05.01:15:31.315>
labels = ['expert-IO', 'docs']
title = 'io.TextIOBase.buffer is not necessarily a buffer'
updated_at = <Date 2020-06-05.01:15:31.315>
user = 'https://github.com/manueljacob'

bugs.python.org fields:

activity = <Date 2020-06-05.01:15:31.315>
actor = 'mjacob'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'IO']
creation = <Date 2020-06-05.01:15:31.315>
creator = 'mjacob'
dependencies = []
files = []
hgrepos = []
issue_num = 40868
keywords = []
message_count = 1.0
messages = ['370744']
nosy_count = 2.0
nosy_names = ['docs@python', 'mjacob']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue40868'
versions = []

Linked PRs

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").

I'll grab this.
[Hello from PyCon Sprints]
Focus on just updating the documentation rather than introducing any breaking changes.

gh-85045: clarified that the underlying buffer of a TextIOBase can be…

pythongh-85045: clarified that the underlying buffer of a TextIOBase …

[3.14] gh-85045: clarified that the underlying buffer of a TextIOBase…

[3.13] gh-85045: clarified that the underlying buffer of a TextIOBase…

thanks!

pythongh-85045: clarified that the underlying buffer of a TextIOBase …

Navigation Menu

Repository navigation

io.TextIOBase.buffer is not necessarily a buffer #85045

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

io.TextIOBase.buffer is not necessarily a buffer #85045

Description

Linked PRs

Activity

manueljacob commented on Jun 5, 2020

AlexKautz commented on May 20, 2025

gpshead commented on May 20, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions