CODEWITHSUNDEEP
python
behindalens
behindalens

Reputation: 465

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

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

Upvotes: 36

Views: 17533

Answers (4)

Bandi-T
Bandi-T

Reputation: 3319

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

Upvotes: 2

pavium
pavium

Reputation: 15118

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.

Upvotes: 1

Stephan202
Stephan202

Reputation: 61529

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.

Upvotes: 30

Jeremy Wall
Jeremy Wall

Reputation: 25237

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

Upvotes: 2

Related Questions