What Do Square Brackets, "[]", Mean in Function/Class Documentation

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

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.

What does square bracket mean in args of function docs?

Its the documentation style:

Here are the few examples:

image = cv2.imread("my_image.jpg") # src

# resize the image to 200x200px, ignoring aspect ratio
resized = cv2.resize(image, (200, 200))
cv2.imshow("Fixed Resizing", resized)

and

# fixed resizing and distort aspect ratio 
# to be 300px but compute the new height based on the aspect ratio
image = cv2.imread("my_image.jpg") # src
(h, w, d) = image.shape
print("width={}, height={}, depth={}".format(w, h, d))
r = 300.0 / w
dim = (300, int(h * r))
resized = cv2.resize(image, dim)
cv2.imshow("Aspect Ratio Resize", resized)

int([x[, base]]). Square brackets in functions in Python documentation?

Everything that is in square brackets is optional, i.e. you can omit it. If the square brackets contain more than 1 argument, you can't choose which ones to omit, you must either specify all of them, or none.

That's where nested brackets come in handy:

int([x[, base]])

Here, for example, you can use int() without arguments (by omitting the whole outer bracket) or int(x) (by omitting the inner bracket) or int(x, base). But not int(base) (well, that would just mean int(x)).

This isn't actual Python syntax, just a way for documentation to be clearer. Python 3's documentation tries to avoid these brackets.

What does it mean in documentation when arguments are in square brackets?

It means optional arguments.

It is not python specific syntax, it is more general grammar notation syntax, for example, from https://en.wikipedia.org/wiki/Extended_Backus–Naur_form:

Many BNF specifications found online today are intended to be human-readable and are non-formal. These often include many of the following syntax rules and extensions:

Optional items enclosed in square brackets: [].

Better explanation in https://en.wikipedia.org/wiki/Extended_Backus–Naur_form, Basics chapter.

What do the square brackets around parameters mean in the official documentation?

This notation is described in the documentation introduction:

a phrase enclosed in square brackets ([ ]) means zero or one occurrences (in other words, the enclosed phrase is optional).

The documentation you link to also explains the parameters:

All arguments are optional and default to 0. Arguments may be ints, longs, or floats, and may be positive or negative.

---

The short version: If a parameter is enclosed in square brackets, it is optional.

What do the brackets around the arguments mean when reading documentation for a method?

required [optional] <required> [<optional>, <but both needed>].

This is almost always the case.

What does the brackets with comma around input arguments mean in python documentations?

It's a common convention in documentation to denote optional arguments with square brackets. That documentation is telling you that the second argument to boxPoints is optional. It has no syntactic meaning in Python; you can call the function with one or two arguments like normal.

---

Related Topics