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

Question

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

Answer 1

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.

Answer 2

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

Answer 3

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

Answer 4

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.