Repository navigation
Unification of read() and readline() argument names #61205
Description
| BPO | 17003 |
|---|---|
| Nosy | @pitrou, @tiran, @benjaminp, @hynek, @vadmium, @serhiy-storchaka |
| Files |
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 = 'https://github.com/serhiy-storchaka'
closed_at = <Date 2017-03-07.17:44:28.982>
created_at = <Date 2013-01-20.16:13:14.470>
labels = ['type-feature', 'library', 'expert-IO', 'docs']
title = 'Unification of read()\xc2\xa0and readline() argument names'
updated_at = <Date 2017-03-07.17:44:28.981>
user = 'https://github.com/serhiy-storchaka'bugs.python.org fields:
activity = <Date 2017-03-07.17:44:28.981>
actor = 'serhiy.storchaka'
assignee = 'serhiy.storchaka'
closed = True
closed_date = <Date 2017-03-07.17:44:28.982>
closer = 'serhiy.storchaka'
components = ['Documentation', 'Library (Lib)', 'IO']
creation = <Date 2013-01-20.16:13:14.470>
creator = 'serhiy.storchaka'
dependencies = []
files = ['28798']
hgrepos = []
issue_num = 17003
keywords = ['patch']
message_count = 9.0
messages = ['180298', '180300', '180302', '180303', '180304', '196477', '197943', '233748', '233758']
nosy_count = 10.0
nosy_names = ['pitrou', 'christian.heimes', 'benjamin.peterson', 'stutzbach', 'docs@python', 'tshepang', 'python-dev', 'hynek', 'martin.panter', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue17003'
versions = ['Python 3.4']
Activity
serhiy-storchaka commentedon Jan 20, 2013
read() and readline() optional parameter which limit the amount of read data has different names in different classes. All this classes mimic (less or more) io classes. Keyword parameter name is a part of method specification. Therefore it will be good made all read() arguments names the same and all readline() arguments names the same (and be consistent with documentation and C implementation). At least we should choose most consistent name for new implementations. If existent C implementation of some method doesn't support keyword argument (all _io classes) or argument names in C and Python implementations are different then we are free to change this name without breaking existing code.
For example, read()'s parameter named as:
"n" in _pyio, zipfile, and io documentation;
"size" in gzip, bz2, imaplib, tarfile, codecs, mailbox;
"len" in ssl;
"wtd" or "totalwtd" in binhex;
"amt" in http/client;
"chars" in codecs;
"buffersize" in os.
readline()'s parameter named as:
"limit" in _pyio, zipfile, and io documentation;
"size" in gzip, bz2, codecs, mailbox, lzma.
serhiy-storchaka commentedon Jan 20, 2013
Looks as size is most common parameter name for both read() and readline(). First, we can change the io documentation and _pyio signatures (it shouldn't break anything because _io doesn't support keyword arguments).
pitrou commentedon Jan 20, 2013
"n" is the best choice IMO. "size" is ok too, although it may be confused with the byte-size of the result.
serhiy-storchaka commentedon Jan 20, 2013
Here is a patch which changes name of optional parameter of read(), read1(), peek(), and readline() methods to most common name "size" in the documentation and _pyio module. truncate() in _pyio fixed to conform with documentation. This changes are safe.
There is open question about readlines(). It's optional parameter named as:
"hint" in _pyio and the documentation;
"size" in bz2;
"sizehint" in codecs and mailbox.
serhiy-storchaka commentedon Jan 20, 2013
Unfortunately most stdlib modules vote for "size".
serhiy-storchaka commentedon Aug 29, 2013
Are there any objections to the patch?
python-dev commentedon Sep 16, 2013
New changeset 46c1c2b34e2b by Serhiy Storchaka in branch 'default':
Issue bpo-17003: Unified the size argument names in the io module with common
http://hg.python.org/cpython/rev/46c1c2b34e2b
vadmium commentedon Jan 9, 2015
Is there anything left for this bug or could it be closed? I can confirm my v3.4.2 docs say “size” instead of “n” :)
serhiy-storchaka commentedon Jan 9, 2015
readlines() parameter name is not unified still (it can be "hint", "size", "sizehint"). There is no obvious winner.