classification
Title: Improve doc for csv.DictReader 'fieldnames' parameter
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, python-dev, r.david.murray, rogererens, sean.rodman
Priority: normal Keywords: patch

Created on 2014-02-14 17:43 by rogererens, last changed 2014-02-24 20:39 by r.david.murray. This issue is now closed.

Files
File name Uploaded Description Edit
DictReader_DictWriter_python3_NewWording.patch sean.rodman, 2014-02-18 20:25 Python 3 patch for DictReader and DictWriter documentation to clarify that fieldnams is a sequence with a link to the collections absctract for reference. Also, added a couple of sentences about the importance of the order of the elements in fieldnames review
DictReader_DictWriter_python2_ref.patch sean.rodman, 2014-02-20 19:37 Updated Python 2.7 patch using a ref to the collections abc review
Messages (22)
msg211226 - (view) Author: Roger Erens (rogererens) Date: 2014-02-14 17:43
The sections on DictReader and DictWriter do not give information on what the type is of the parameter 'fieldnames'. The source code comments that it is a 'list of keys for the dict'.
msg211233 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-14 18:35
Fieldnames is referred to as a sequence, which does define its type.  That said, defining the type earlier in that paragraph would probably be a good thing.
msg211245 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-14 22:47
I am new to contributing to python, and I would like to take a shot a creating a patch for this.
msg211246 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-14 22:57
I have created a patch for this documentation issue. Could you please review this for me and tell me what you think?
msg211361 - (view) Author: Roger Erens (rogererens) Date: 2014-02-16 21:37
I did not fully realize the meaning of it being a sequence as it is referred to a little later indeed. Which implies both a tuple and a list can be used, right? So then the patch might look like:

+   The *fieldnames* parameter is a list or tuple of keys used for the dict.
msg211363 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-16 21:47
It looks like you are right. I have updated the patch to reflect that it could be a list or a tuple.
msg211518 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-18 16:08
Well, there is a reason why the term 'sequence' was used.  It covers lists, tuples...and anything else that implements the Sequence ABC (http://docs.python.org/library/collections.html#collections-abstract-base-classes).

The word 'sequence' could be made a link to that section by doing:

  :mod:`sequence <collections.abc>`

in the Python3 docs (it would need to be a :ref: to the subsection in the python2 docs, I think).
msg211530 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-18 17:45
Here is a patch for DictReader that adds a mod link to the sequence abstract as requested. Please review this if you could and let me know what you think. Note: This patch is for python 3 and if you like how I have done it on here I will go ahead and create a patch that covers python 2 as well.
msg211532 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-18 17:56
I'd like to combine the two approaches: mention that fieldnames is a sequence (with the link) as soon as fieldnames is introduced in the paragraph, analogous to what you did in the first patch.  Whether you then make what becomes the second occurrence of the word sequence also a link is a matter of taste, but I probably wouldn't.
msg211534 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-18 18:09
Ok, I have take the approach I used with the original patch and applied it to this one, listing that fieldnames is a sequence. Then, I added a link to the collections abstract on that instance of the word sequence. I did this for both DictReader and DictWriter as I did in the original patch. Would this be what you think is needed?
msg211535 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-18 18:20
This looks pretty good.  In the DictReader part, it might be good to add something analogous to the DictWriter clarifying what the order of the sequence means.  Something like "a :mod:`sequence <collections.abc>` whose elements are associated with the fields of the input data in order, and which become the keys of the resulting dictionary".  If think you have a way to improve that wording, please try, as I'm not entirely happy with it :)
msg211546 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-18 20:25
What about if I put "The *fieldnames* parameter is a :mod:`sequence <collections.abc>` whose elements are associated with the fields of the input data in order. These elements become the keys of the resulting dictionary." It contains all of the information that you have but it feels more to the point when you separate it as two sentences. The attached patch reflect these changes.
msg211564 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-18 22:44
Yes, that does sound better.  If you can make an equivalent 2.7 patch I will apply them.
msg211580 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-19 01:02
Here is the equivalent 2.7 patch. I used a relative link with the format `sequence <collections.html>`_ in order to link to the collections page. I tried to use the reference syntax but I could find the subsection that I needed to reference in the documentation. If you would like for me to go that route I don't mind trying to figure it out, this is just the way I was able to get the documentation compiling and working correctly.
msg211582 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-19 01:04
That is supposed to say I couldn't find the subsection that I needed to reference in the documentation.
msg211736 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-20 16:39
I just realized that my two last updates on this ticket could be sort of confusing. So here is what I did for the 2.7 patch. First I copied the wording that I used for the 3.3/4 patch and then I created a relative link using the syntax `sequence <collections.html>`_ because I couldn't find a way to get the :ref: syntax to work correctly. I have applied this patch to the 2.7 branch and compiled the html documentation. When I tested it the link does work correctly. It goes to the collections page of the documentation. If you have time could you review the patch for 2.7 for me? (The patch is named DictReader_DictWriter_python2_NewWording.patch.)
msg211738 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-20 17:30
I figured out what you meant, but thanks for the clarification.

The section of interest in 2.7 is near the bottom of the page you linked to.  It already has a Sphinx section reference (collections-abstract-base-classes), so you can use :ref: to link to it.
msg211747 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-20 19:37
Great! Thank you for the reference name. I have changed the patch to use a ref link. Here is the new patch.
msg211922 - (view) Author: Roger Erens (rogererens) Date: 2014-02-22 12:57
One more nitpick: is it the sequence [of keys] that identif_ies_ the order, or is it the keys that identif_y_ the order? Not being a native English speaker, I'd opt for the first choice.
Thank you both for your meticulous attention for details!
msg212134 - (view) Author: Sean Rodman (sean.rodman) * Date: 2014-02-24 19:19
Is there anything else that should be added to this patch? I don't mean to bug you guys just want to make sure that everything is right with it so that if and or when it is applied it will apply without any problems. Also, if there is anything else I should change I am definitely open to changing anything that is needed.
msg212136 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-02-24 20:37
New changeset a5d4660c6cb6 by R David Murray in branch '3.3':
#20628: make it clear that DictReader/Writer *fieldnames* is a Sequence.
http://hg.python.org/cpython/rev/a5d4660c6cb6

New changeset 9f036047187b by R David Murray in branch '3.3':
#20628: wrap lines to < 80.
http://hg.python.org/cpython/rev/9f036047187b

New changeset 5eb7e29df762 by R David Murray in branch 'default':
Merge #20628: make it clear that DictReader/Writer *fieldnames* is a Sequence.
http://hg.python.org/cpython/rev/5eb7e29df762

New changeset 0e77dd295a88 by R David Murray in branch '2.7':
#20628: make it clear that DictReader/Writer *fieldnames* is a Sequence.
http://hg.python.org/cpython/rev/0e77dd295a88

New changeset 0926adcc335c by R David Murray in branch '2.7':
#20628: wrap lines to < 80.
http://hg.python.org/cpython/rev/0926adcc335c
msg212137 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-24 20:39
Applied.  Thanks, Sean.
History
Date User Action Args
2014-02-24 20:39:10r.david.murraysetstatus: open -> closed
resolution: fixed
messages: + msg212137

stage: resolved
2014-02-24 20:37:25python-devsetnosy: + python-dev
messages: + msg212136
2014-02-24 19:19:08sean.rodmansetmessages: + msg212134
2014-02-22 12:57:20rogererenssetmessages: + msg211922
2014-02-21 21:40:11terry.reedysettitle: csv.DictReader -> Improve doc for csv.DictReader 'fieldnames' parameter
2014-02-20 19:38:05sean.rodmansetfiles: - DictReader_DictWriter_python2_NewWording.patch
2014-02-20 19:37:55sean.rodmansetfiles: + DictReader_DictWriter_python2_ref.patch

messages: + msg211747
2014-02-20 17:30:02r.david.murraysetmessages: + msg211738
2014-02-20 16:39:22sean.rodmansetmessages: + msg211736
2014-02-19 01:04:29sean.rodmansetmessages: + msg211582
2014-02-19 01:02:38sean.rodmansetfiles: + DictReader_DictWriter_python2_NewWording.patch

messages: + msg211580
2014-02-18 22:44:03r.david.murraysetmessages: + msg211564
versions: + Python 3.3
2014-02-18 20:25:59sean.rodmansetfiles: - DictReader_DictWriter_python3.patch
2014-02-18 20:25:50sean.rodmansetfiles: + DictReader_DictWriter_python3_NewWording.patch

messages: + msg211546
2014-02-18 18:20:01r.david.murraysetmessages: + msg211535
2014-02-18 18:09:42sean.rodmansetfiles: + DictReader_DictWriter_python3.patch

messages: + msg211534
2014-02-18 18:05:35sean.rodmansetfiles: - DictReader_python3.patch
2014-02-18 18:05:26sean.rodmansetfiles: - DictReader_DictWriter_2.patch
2014-02-18 17:56:42r.david.murraysetmessages: + msg211532
2014-02-18 17:45:37sean.rodmansetfiles: + DictReader_python3.patch

messages: + msg211530
2014-02-18 16:08:26r.david.murraysetmessages: + msg211518
2014-02-16 21:48:48sean.rodmansetfiles: - DictReader_DictWriter.patch
2014-02-16 21:47:38sean.rodmansetfiles: + DictReader_DictWriter_2.patch

messages: + msg211363
2014-02-16 21:37:19rogererenssetmessages: + msg211361
2014-02-14 22:57:59sean.rodmansetfiles: + DictReader_DictWriter.patch
keywords: + patch
messages: + msg211246
2014-02-14 22:47:38sean.rodmansetnosy: + sean.rodman
messages: + msg211245
2014-02-14 18:35:16r.david.murraysetnosy: + r.david.murray
messages: + msg211233
2014-02-14 17:43:34rogererenscreate