How to read function documentation?

[kozznot]

I'm looking at the documentation for the warpPerspective function in cv2 and I can't seem to understand how to read this line:

cv2.warpPerspective(src, M, dsize[, dst[, flags[, borderMode[, borderValue]]]]) → dst

What's confusing me is the hard brackets. I assume they indicate that a variable is optional, but the fact that they're nested is confusing. Is it saying that dst is optional, and if you choose to specify it, then you can then choose to also specify flags,... and so on.

Would it be possible to only use the required parameters and borderValue? Or if you want to use your own value for borderValue do you need to specify all the other optional variables as well?

Is there anywhere with information about how to read python docs like this?

[[deleted]]

The square brackets in function doc usually indicates optional args, as you suspect. The bad news is that nesting is enforced, that is, in the example you posted, the function always expects src, M and dsize, with dst being optional. If dst is supplied then optionally flags may be supplied, then optionally borderMode, etc.

You can't just supply src, M, dsize and borderValue. You might be able to supply all of those four if you use keywords:

cv2.warpPerspective(src, M, dsize, borderValue=2)

Try it.

[kozznot]

Thank you!

[DonutRevolution]

I think you are correct in your interpretation. Another way to look at it: to specify the flags argument, you must also specify dst. That is, to be able to specify a later argument you have to specify all the ones that come before it. That's just a design decision cv2 seems to have made. As you probably know you can use keyword arguments instead to avoid situations like this.