35

I am having trouble figuring out the arguments to csv.dictreader and realized I have no clue what the square brackets signify.

From the docmentation:

class csv.DictReader(csvfile[, fieldnames=None[, restkey=None[, restval=None[, dialect='excel'[, *args, **kwds]]]]])

I'd appreciate a summary of the arguments to the class instantiation.

Thanks

Jed Smith
  • 15,584
  • 8
  • 52
  • 59
behindalens
  • 455
  • 1
  • 6
  • 8
  • related: [How to read API documentation](http://stackoverflow.com/q/10925478/1048572) – Bergi Mar 07 '15 at 18:16
  • possible duplicate of [What does \[, element\] mean?](http://stackoverflow.com/questions/17752417/what-does-element-mean) – Bergi Mar 07 '15 at 18:16

4 Answers4

29

The square brackets indicate that these arguments are optional. You can leave them out.

So, in this case you are only required to pass the csvfile argument to csv.DictReader. If you would pass a second parameter, it would be interpreted as the fieldnames arguments. The third would be restkey, etc.

If you only want to specify e.g. cvsfile and dialect, then you'll have to name the keyword argument explicitly, like so:

csv.DictReader(file('test.csv'), dialect='excel_tab')

For more on keyword arguments, see section 4.7.2 of the tutorial at python.org.

Stephan202
  • 59,965
  • 13
  • 127
  • 133
  • This answer is correct. There's just one thing I would add. Although cvs.DictReader takes keyword arguments, you can have non-keyword arguments with defaults too. These tend to be in builtin functions written in C, like the global 'range()' function, or the 'split()' method on a string. The documentation for 'split' on a string gives its arguments like this: S.split([sep, [,maxsplit]]) -> list of strings You might therefore think this would work: "a b c d e f g".split(maxsplit=2) but, sadly, it doesn't. Python throws an "TypeError: split() takes no keyword arguments" exception. Sigh. – Larry Hastings Nov 12 '09 at 00:51
  • Is there a difference between optional versus default arguements? What would be the difference between: def exampleFunc1(arg1, [arg2 = 2], [arg3 = 3]): and def exampleFunc2(arg1, arg2 = 2, arg3 = 3): Thanks – behindalens Nov 13 '09 at 16:43
  • @behindalens: in both cases `arg2` and `arg3` can be omitted, in which case their value would be `2` and `3`, respectively. Optional *arguments* can have a default *value*. – Stephan202 Nov 13 '09 at 17:32
  • Is there any significance in the fact that the square brackets are nested? – behindalens Nov 13 '09 at 18:05
  • @behindalens: it more clearly conveys how unnamed optional arguments are interpreted. I suppose the unnested version could mean something else, namely that these optional arguments *must* be named because there is no clear ordering (so you'd have to write e.g. `arg2=7`), but then the second comma should be inside the brackets if you ask me: `exampleFunc1(arg1, [arg2 = 2,] [arg3 = 3])`. (But again, perhaps that's just me.) In general, my advice is to carefully read the documentation, and when in doubt just write some test code. That's what I do :) – Stephan202 Nov 13 '09 at 18:15
  • @Stephan202: To summarize, nesting square brackets indicates some order in the optional arguments. Is this usually standard for similar language documentation? – behindalens Nov 13 '09 at 19:46
  • Yes, you'll also find this notation elsewhere, e.g. in manpages (http://en.wikipedia.org/wiki/Man_page) – Stephan202 Nov 13 '09 at 20:08
2

Usually in api documentation square brackets mean optional. I would think they mean the same here.

Jeremy Wall
  • 23,907
  • 5
  • 55
  • 73
2

This is actually a subset of the widely used notation to unambiguously describe language syntax called Backus-Naur Form (see Wikipedia article for details).

Bandi-T
  • 3,231
  • 1
  • 20
  • 15
1

To reiterate what the others have said, the arguments are optional.

If you leave out optional parts, the remaining fieldnames=, restval=, restkey= or dialect= keywords tell the function which parts are missing.

The syntax doesn't suggest it, but I wouldn't be surprised if the keywords allow the arguments to be specificied in any order, except that the last two arguments must be either both specified, or both omitted.

pavium
  • 14,808
  • 4
  • 33
  • 50
  • Indeed keyword arguments can be specified in any order. That's (part of) their appeal. Also, functions which take arbitrarily many keyword arguments do so with the `**kwargs` parameter, which is a `dict`. As you know, `dict` objects do not maintain order. – Stephan202 Nov 12 '09 at 00:11
  • @pavium: How is it indicated that the last two arguments **both** be specified or omitted? – behindalens Nov 13 '09 at 19:21
  • They are *both* inside a single set of brackets. – pavium Nov 13 '09 at 19:38