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

Question

Redo:

(Shorter version just for Stephen202)

What is the significance in putting the comma after after the open bracket, instead of before? And, what is the significance of nesting the brackets.

How they are:

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

What I would expect:

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

WHY ARE THE BRACKETS NESTED INSTEAD OF JUST LIKE THIS:

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

Why can you back the first bracket into the required argument and that works, but then backing the second bracket into the first is just bletch? This nested nature is what confuses me the most, and not one out of 7 answers has answered that. cvondrick gets the nugget because at lest he answered the comma part and now I understand that.

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])

Answer 2

The open bracket indicates an optional argument. If the comma were outside the bracket, you would have to type it even if you didn't want to use the pos argument (for example).

Answer 3

Because otherwise the correct syntax would be to include the comma even if you are ignoring the arguments. The parts inside the square brackets are optional, so by moving the commas out of the square brackets, they are no longer optional. For example, to call the function below with only a string:

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

I would have to do:

RegexObject.match("foobar",,)

But, that isn't very elegant.

Answer 4

If you think about the brackets enclosing all optional components of the argument list, it makes more sense. Essentially, anything inside brackets may be left out at the discretion of the user.

Answer 5

The brackets mean that you can leave out the part between them. So if the docs would be written the way you suggest, it would imply that you can write RegexObject.match(string,,) by leaving everything in brackets. Or RegexObject.match(string,,endpos) by just leaving out the second one. But you can't. If you leave out endpos, you also have to leave out the comma before it. And if you leave out pos, you have to leave out the comma before it as well as endpos. So it's written in a way that makes that clear.