[issue17003] Unification of read() and readline() argument names
New submission from Serhiy Storchaka: 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. ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 180298 nosy: benjamin.peterson, christian.heimes, docs@python, hynek, pitrou, serhiy.storchaka, stutzbach priority: normal severity: normal status: open title: Unification of read() and readline() argument names type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Serhiy Storchaka added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Antoine Pitrou added the comment: "n" is the best choice IMO. "size" is ok too, although it may be confused with the byte-size of the result. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Serhiy Storchaka added the comment: 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. ---------- keywords: +patch stage: -> patch review Added file: http://bugs.python.org/file28798/io_parameter_names.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Serhiy Storchaka added the comment:
"n" is the best choice IMO.
Unfortunately most stdlib modules vote for "size". ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Serhiy Storchaka added the comment: Are there any objections to the patch? ---------- assignee: docs@python -> serhiy.storchaka versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Martin Panter added the comment: 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” :) ---------- nosy: +vadmium _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Serhiy Storchaka added the comment: readlines() parameter name is not unified still (it can be "hint", "size", "sizehint"). There is no obvious winner. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
Changes by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________
participants (5)
-
Antoine Pitrou -
Martin Panter
-
Roundup Robot
-
Serhiy Storchaka
-
Tshepang Lekhonkhobe