classification
Title: Unification of read() and readline() argument names
Type: enhancement Stage: resolved
Components: Documentation, IO, Library (Lib) Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: serhiy.storchaka Nosy List: benjamin.peterson, christian.heimes, docs@python, hynek, martin.panter, pitrou, python-dev, serhiy.storchaka, stutzbach, tshepang
Priority: normal Keywords: patch

Created on 2013-01-20 16:13 by serhiy.storchaka, last changed 2017-03-07 17:44 by serhiy.storchaka. This issue is now closed.

Files
File name Uploaded Description Edit
io_parameter_names.patch serhiy.storchaka, 2013-01-20 17:19 review
Messages (9)
msg180298 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-01-20 16:13
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.
msg180300 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-01-20 16:22
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).
msg180302 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-01-20 17:14
"n" is the best choice IMO. "size" is ok too, although it may be confused with the byte-size of the result.
msg180303 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-01-20 17:19
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.
msg180304 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-01-20 17:21
> "n" is the best choice IMO.

Unfortunately most stdlib modules vote for "size".
msg196477 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-08-29 18:29
Are there any objections to the patch?
msg197943 - (view) Author: Roundup Robot (python-dev) Date: 2013-09-16 20:18
New changeset 46c1c2b34e2b by Serhiy Storchaka in branch 'default':
Issue #17003: Unified the size argument names in the io module with common
http://hg.python.org/cpython/rev/46c1c2b34e2b
msg233748 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-01-09 12:41
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” :)
msg233758 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-01-09 15:03
readlines() parameter name is not unified still (it can be "hint", "size", "sizehint"). There is no obvious winner.
History
Date User Action Args
2017-03-07 17:44:28serhiy.storchakasetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2015-01-09 15:03:32serhiy.storchakasetmessages: + msg233758
2015-01-09 12:41:07martin.pantersetnosy: + martin.panter
messages: + msg233748
2013-09-16 20:18:26python-devsetnosy: + python-dev
messages: + msg197943
2013-08-29 18:29:33serhiy.storchakasetassignee: docs@python -> serhiy.storchaka
messages: + msg196477
versions: + Python 3.4
2013-01-26 17:17:06tshepangsetnosy: + tshepang
2013-01-20 17:21:36serhiy.storchakasetmessages: + msg180304
2013-01-20 17:19:47serhiy.storchakasetfiles: + io_parameter_names.patch
keywords: + patch
messages: + msg180303

stage: patch review
2013-01-20 17:14:49pitrousetmessages: + msg180302
2013-01-20 16:22:49serhiy.storchakasetmessages: + msg180300
2013-01-20 16:13:14serhiy.storchakacreate