io doc improvements

[pitrou]

BPO	9715
Nosy	@smontanaro, @pitrou, @benjaminp
Files	iodoc.patch

^{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 = <Date 2010-08-30.12:49:56.404>
created_at = <Date 2010-08-30.11:54:39.441>
labels = ['type-bug', 'expert-IO', 'docs']
title = 'io doc improvements'
updated_at = <Date 2010-08-30.14:23:20.149>
user = 'https://github.com/pitrou'

bugs.python.org fields:

activity = <Date 2010-08-30.14:23:20.149>
actor = 'pitrou'
assignee = 'docs@python'
closed = True
closed_date = <Date 2010-08-30.12:49:56.404>
closer = 'pitrou'
components = ['Documentation', 'IO']
creation = <Date 2010-08-30.11:54:39.441>
creator = 'pitrou'
dependencies = []
files = ['18680']
hgrepos = []
issue_num = 9715
keywords = ['patch']
message_count = 7.0
messages = ['115208', '115211', '115212', '115213', '115214', '115216', '115217']
nosy_count = 4.0
nosy_names = ['skip.montanaro', 'pitrou', 'benjamin.peterson', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue9715'
versions = ['Python 3.1', 'Python 3.2']

[pitrou]

This is an improvement patch for the :mod:`io` documentation.
It adds an user-friendly overview, and makes a couple of other fixes/improvements.
There's a problem where I want to make a link to a glossary term while using the plural form ("abstract base classes"), and it doesn't work. Can someone help me?

[pitrou]

Ok, committed in r84357 (py3k) and r84358 (3.1). Backporting to 2.7 would be too much work.

[smontanaro]

A couple wording comments:

"All streams are careful about the type of data you give to them"
would read better as "All streams accept specific types of data".

"The default mode is 'r' (open for reading text, synonym of
'rt')". I liked the original wording better.

Finally, not specific to this change, but I wonder if rather than
having distinct io.StringIO and io.BytesIO classes it would be better
to have a single io.MemoryIO class which takes mode arguments just
like io.FileIO? The correspondence between file-based and memory-
based i/o would be more one-to-one. Such a class could be added
without breaking existing code by using the StringIO and BytesIO
classes as the back-end for a MemoryIO class.

[benjaminp]

2010/8/30 Skip Montanaro report@bugs.python.org:

Skip Montanaro skip@pobox.com added the comment:

A couple wording comments:

"All streams are careful about the type of data you give to them"
would read better as "All streams accept specific types of data".

"The default mode is 'r' (open for reading text, synonym of
'rt')".  I liked the original wording better.

Feel free to change it; it's been committed.

Finally, not specific to this change, but I wonder if rather than
having distinct io.StringIO and io.BytesIO classes it would be better
to have a single io.MemoryIO class which takes mode arguments just
like io.FileIO?  The correspondence between file-based and memory-
based i/o would be more one-to-one.  Such a class could be added
without breaking existing code by using the StringIO and BytesIO
classes as the back-end for a MemoryIO class.

What advantage would that have?

[pitrou]

"The default mode is 'r' (open for reading text, synonym of
'rt')". I liked the original wording better.

Well, people use "r" in practice, and "rt" is a somewhat rarer
alternative. We could drop the "synonym..." part entirely.

[smontanaro]

> Finally, not specific to this change, but I wonder if rather than
>> having distinct io.StringIO and io.BytesIO classes it would be better
>> to have a single io.MemoryIO class which takes mode arguments just
>> like io.FileIO?  The correspondence between file-based and memory-
>> based i/o would be more one-to-one.  Such a class could be added
>> without breaking existing code by using the StringIO and BytesIO
>> classes as the back-end for a MemoryIO class.

Benjamin> What advantage would that have?

File I/O and memory I/O would have more uniform in their APIs and thus be
easier to document, describe and use. Currently, one class is used to do
file I/O. The type of I/O done is controlled by the mode and buffering
flags. Two distinct classes are used to do memory I/O.

If someone wanted to select between file and memory I/O at runtime it
wouldn't be possible to just swap the class using the current code.

Skip

[pitrou]

File I/O and memory I/O would have more uniform in their APIs and thus be
easier to document, describe and use. Currently, one class is used to do
file I/O.

That's wrong. Various classes are used for file I/O: FileIO,
Buffered{Reader,Writer,Random}, TextIOWrapper.

If someone wanted to select between file and memory I/O at runtime it
wouldn't be possible to just swap the class using the current code.

Why would you swap the class since the constructor arguments would be
different anyway?