How to read typical function documentation in Python?

Question

Why does

class multiprocessing.Pool([processes[,initializer[,initargs[,maxtasksperchild]]]]) 

have all these ]]]] included?

I don't understand how to read this structure?

Answer 1

"a phrase enclosed in square brackets ([ ]) means zero or one occurrences (in other words, the enclosed phrase is optional)"

See http://docs.python.org/2/reference/introduction.html#notation

[processes[,initializer[,initargs[,maxtasksperchild]]]] means for instance that initializer is optional but if you use initializer you must also use processes and so on. This is what the embedded brackets mean.

If you do not name the parameters you can use in any of the following examples (but no other combination!):

Pool() 
Pool(processes) 
Pool(processes, initializer) 
Pool(processes, initializer, initargs) 
Pool(processes, initializer, initargs, maxtasksperchild) 

Otherwise if you do name the parameteres you can use any of them optionally. The constructor has following default values:

Pool(processes=None, initializer=None, initargs=(), maxtasksperchild=None)

See the source code of the constructor (https://bitbucket.org/pypy/pypy/src/9d88b4875d6e/lib-python/2.7/multiprocessing/pool.py)

For more on keyword arguments you can read the following: http://docs.python.org/3/tutorial/controlflow.html#keyword-arguments

Answer 2

Usually, in documentation, [something] is read like 'something is optional'. In this particular case, it also implies dependency and should be read like this:

• processes is optional, but if you use it you can also use:
• initializer, which is optional, but if you use it you can also use:
• initargs, which is optional, but... and so on