This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: declare that Text I/O use buffer inside
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Windson Yang, docs@python, methane
Priority: normal Keywords:

Created on 2019-08-14 02:44 by Windson Yang, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Messages (4)
msg349633 - (view) Author: Windson Yang (Windson Yang) * Date: 2019-08-14 02:44
At the beginning of, we declared that 

> Binary I/O (also called buffered I/O)
> Raw I/O (also called unbuffered I/O)

But we didn't mention if Text I/O use buffer or not which led to confusion. Even though we talked about it later in

> The TextIOBase ABC, another subclass of IOBase, deals with streams whose bytes represent text, and handles encoding and decoding to and from strings. TextIOWrapper, which extends it, is a buffered text interface to a buffered raw stream (BufferedIOBase). Finally, StringIO is an in-memory stream for text.

IMO, it will be better to declare 'Reads and writes are internally buffered in order to speed things up' at the very beginning in 

> Text I/O
> Text I/O expects and produces str objects...

or maybe

> class io.TextIOBase
> Base class for text streams. This class provides a character and line based interface to stream I/O. It inherits IOBase. There is no public constructor.
msg349647 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2019-08-14 05:47
It's just an implementation detail.  Python implementation and C implementation behave slightly different.  But user program shouldn't rely on the detail.

Why do you think implementation details should be declared?
Who needs the information?
msg349651 - (view) Author: Windson Yang (Windson Yang) * Date: 2019-08-14 06:20
I found the document is not that clear when I try to understand what happens when Python read/write a file. I'm not sure who also needs this information. As you said, It wouldn't help the user program in Python. However, make it more clear maybe help users have a better feeling of what is happening under the hood.
msg367079 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2020-04-23 05:29
I still think it's too detailed.
Reading C and Python code is much better way to understand such implementation detail.
Date User Action Args
2022-04-11 14:59:19adminsetgithub: 82027
2020-04-23 05:29:32methanesetstatus: open -> closed
resolution: rejected
messages: + msg367079

stage: resolved
2019-08-14 06:20:57Windson Yangsetmessages: + msg349651
2019-08-14 05:47:14methanesetnosy: + methane
messages: + msg349647
2019-08-14 02:44:09Windson Yangcreate