[issue16026] csv.DictReader argument names documented incorrectly
New submission from Peter Eisentraut: The documentation for the csv.DictReader constructor is .. class:: DictReader(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds) but the implementation is def __init__(self, f, fieldnames=None, restkey=None, restval=None, dialect="excel", *args, **kwds): The name of the first argument is documented incorrectly, leading to surprise errors when attempting to use key word arguments. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 171161 nosy: docs@python, petere priority: normal severity: normal status: open title: csv.DictReader argument names documented incorrectly type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +easy stage: -> needs patch versions: -Python 2.6, Python 3.1, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
James Salt added the comment: This diff shows a correction of the documentation to reflect the name for the csv file used in the implementation - this change seemed like the easiest and simplest thing to do and avoids potential backwards incompatibility issues. ---------- nosy: +James.Salt Added file: http://bugs.python.org/file27338/james.salt-corrections_to_documentation_in_... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Larry Hastings added the comment: Eric, iirc you're the de facto csv guy? Does this seem reasonable to you? ---------- nosy: +eric.araujo, larry _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Éric Araujo added the comment: I’m not a dedicated maintainer for csv (for one thing I don’t know C :), I just happen to reply to many bug reports. This doc patch looks good to me. ---------- nosy: +sandro.tosi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Serhiy Storchaka added the comment: It is not consistent with reader and writer. I propose to close the issue as "won't fix" or change the argument name in the sources. Unfortunately, Python syntax does not allow to specify the positional-only arguments. ---------- keywords: +patch nosy: +storchaka Added file: http://bugs.python.org/file27339/csv_csvfile_arg.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Éric Araujo added the comment: I don’t understand the proposal. Changing the code has a high bar; here it would break code without benefit. Fixing the doc so that it reflects the code accurately is a no-cost improvement. (Inconsistency is unfortunate, but we’ll have to live with that.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Serhiy Storchaka added the comment: Changing the documentation is changing the specification, it has the higher bar than changing the implementation. It can break the alternative implementations. This is unlikely to break somebody's existing code, because the one who used the argument as a keyword argument should have paid attention to the discrepancy of the documentation. But fixing the name, we will be difficult to change it in the future (to eliminate inconsistency). I believe this change is too serious for bugfix. This is the case when never is better than *right* now. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Éric Araujo added the comment: I disagree that we can never fix argument names in the docs, as we have done it already. You raise a good point however, that we should check what other VMs do. I would not be surprised if they followed the code instead of the docs. ---------- keywords: +3.3regression -easy, patch nosy: +benjamin.peterson _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +needs review, patch -3.3regression _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Mohammad Maaz Khan added the comment: Hi Éric, I think the documentation should be changed to match the arguments' names. ---------- nosy: +maaz92 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Berker Peksag added the comment: James Salt's patch looks good to me, but it doesn't apply cleanly anymore. For the record, PyPy uses the same parameter name as Lib/csv.py: https://bitbucket.org/pypy/pypy/src/55a9404c80d6557854cac092addd92a6e0b683cc/lib-python/2.7/csv.py?at=default&fileviewer=file-view-default#csv.py-74 ---------- keywords: +easy -needs review nosy: +berker.peksag priority: normal -> low versions: +Python 3.5, Python 3.6, Python 3.7 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Greg Bengeult added the comment: Here's a revised patch file for Python 3.7. This is my first ever submission to an open source project, so please be gentle. ---------- nosy: +gbengeult versions: -Python 2.7, Python 3.5, Python 3.6 Added file: http://bugs.python.org/file46132/csv.rst-patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Berker Peksag added the comment: Welcome and thanks for the patch, Greg. csv.rst-patch looks good to me. I will commit it this week if there are no objections. Documentation updates can go into all active branches so I'm adding 3.5 and 3.6 back (we can pass 2.7 at this point since this is a trivial change) ---------- stage: needs patch -> patch review versions: +Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Berker Peksag added the comment: Thanks for the patches James and Greg! ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed versions: -Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
Roundup Robot added the comment: New changeset 198edd926751 by Berker Peksag in branch '3.6': Issue #16026: Fix parameter names of DictReader and DictWriter https://hg.python.org/cpython/rev/198edd926751 New changeset 63c5531cfdf7 by Berker Peksag in branch 'default': Issue #16026: Merge from 3.6 https://hg.python.org/cpython/rev/63c5531cfdf7 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16026> _______________________________________
participants (9)
-
Berker Peksag -
Greg Bengeult
-
James Salt
-
Larry Hastings
-
Mohammad Maaz Khan
-
Peter Eisentraut
-
Roundup Robot
-
Serhiy Storchaka
-
Éric Araujo