ansaurus

Question

What do square brackets, "[]", mean in function/class documentation?

Answer 1

+7 A:

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 2009-11-11 23:52:51

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 stringsYou 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 2009-11-12 00:51:48

Is there a difference between optional versus default arguements? What would be the difference between:def exampleFunc1(arg1, [arg2 = 2], [arg3 = 3]):anddef exampleFunc2(arg1, arg2 = 2, arg3 = 3):Thanks

behindalens 2009-11-13 16:43:12

@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 2009-11-13 17:32:55

Is there any significance in the fact that the square brackets are nested?

behindalens 2009-11-13 18:05:44

@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 2009-11-13 18:15:22

@Stephan202: To summarize, nesting square brackets indicates some order in the optional arguments. Is this usually standard for similar language documentation?

behindalens 2009-11-13 19:46:04

Yes, you'll also find this notation elsewhere, e.g. in manpages (http://en.wikipedia.org/wiki/Man_page)

Stephan202 2009-11-13 20:08:16

Answer 2

+2 A:

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

Jeremy Wall 2009-11-11 23:53:13

Answer 3

+1 A:

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 2009-11-12 00:07:55

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 2009-11-12 00:11:24

@pavium: How is it indicated that the last two arguments **both** be specified or omitted?

behindalens 2009-11-13 19:21:09

They are *both* inside a single set of brackets.

pavium 2009-11-13 19:38:09

That is `[, *args, **kwds]`

pavium 2009-11-13 19:43:42

Answer 4

+2 A:

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 2010-01-22 19:44:12

ansaurus

tags:

views:

answers:

What do square brackets, "[]", mean in function/class documentation?

related questions