Python 文档：urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None 中的方括号是什么意思？

Question

I am learning python and came across this description of a function in urllib.request in the documentation of the standard library:

> urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None,
> capath=None, cadefault=False, context=None)

I couldn't figure out what the square brackets around timeout, mean.

I am not even sure how to read the list of parameters of this function: do we have a parameter [timeout and then a parameter ]* separated by a comma, or is [timeout, ]* a parameter as a whole?

In which case, what does the comma after timeout inside the square brackets mean?

Also, what does the star/asterisk mean in this particular case?

Thanks !

Answer 1

Square brackets in parameter documentation generally denote an optional parameter. This not only the case in Python documentation, but is actually a widely-used convention.

So, in this case, it means that timeout is optional, which is confirmed by the documentation text ( bold emphasis mine):

The optional timeout parameter specifies a timeout in seconds for blocking operations like the connection attempt (if not specified, the global default timeout setting will be used). This actually only works for HTTP, HTTPS and FTP connections.

An asterisk in parameter documentation usually means "zero or more repetitions". However, the Python documentation actually uses ellipsis ( … ) for that meaning.

In fact, this asterisk is not actually part of the documentation at all, it is just normal function parameter declaration syntax.

It essentially means "end of positional arguments, everything after this must be passed as a keyword argument".

See Bare asterisk in function arguments? and Forced naming of parameters in Python for more details and PEP 3102 – Keyword-Only Arguments for the specification.