1

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 !

Littm
  • 4,923
  • 4
  • 30
  • 38
Self Learner
  • 23
  • 3
  • It's an optional, __positional__ argument – rdas May 09 '20 at 18:32
  • 1
    Note: it would make it much easier to answer your question if you included a link to the source: https://docs.python.org/library/urllib.request.html#urllib.request.urlopen – Jörg W Mittag May 09 '20 at 18:37

1 Answers1

2

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.

Jörg W Mittag
  • 363,080
  • 75
  • 446
  • 653
  • maybe I am digressing but why didn't they write the function signature to be instead: urlopen(url, data=None, timeout=None, cafile=None, capath=None, cadefault=False, context=None) with timeout being a keyword argument like data, cafile, capath etc... ? ie. why use an optional positional argument for timeout, instead of an optional keyword argument like the others? am I missing something here? many thanks for your helpful answer though! – Self Learner May 09 '20 at 19:25
  • That is a question that only the author of that function can answer. If I had to guess, I would say that, considering that Python is well over 30 years old, the function interface might have been extended multiple times in a backwards-compatible manner. In fact, the documentation lists 6 changes in Python 3 alone. – Jörg W Mittag May 09 '20 at 19:31