Why do Python function docs include the comma after the bracket for optional args?

Question

The format of the function signatures in the Python docs is a bit confusing. What is the significance in putting the comma after the open bracket, rather than before? What is the significance of nesting the brackets?

How they are:

RegexObject.match(string[, pos[, endpos]])

I would expect one of the following:

RegexObject.match(string, [pos], [endpos])
RegexObject.match(string[, pos][, endpos])

Answer 1

The square bracket means that the contents are optional, but everything outside of square brackets is compulsory.

With your notation:

RegexObject.match(string, [pos], [endpos])

I would expect to have to write:

r.match("foo",,)

The nesting is required because if you supply the third parameter then you must also supply the second parameter even though it is an optional parameter. The following non-nested alternative would be ambiguous:

RegexObject.match(string[, pos][, endpos])