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?

Note that I understand that this seems like a stupid silly question (and I agree), but I can't find any official documentation on this kind of presentation. — PascalVKooten
– PascalVKooten, Commented Feb 10, 2014 at 10:11

wolfrevo · Accepted Answer · 2014-02-10 11:00:43Z

4

"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

edited Feb 10, 2014 at 11:00

answered Feb 10, 2014 at 10:22

wolfrevo

7,3792 gold badges34 silver badges46 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Joe Over a year ago

I've seen multiple questions on stack overflow asking how to read Python documentation, and everyone else answers only the particular example presented. This is the first answer I've found that actually links to the answer for "how to read Python documentation".

Mihai · Accepted Answer · 2014-02-10 10:16:41Z

3

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

answered Feb 10, 2014 at 10:16

Mihai

2,1652 gold badges15 silver badges16 bronze badges

2 Comments

PascalVKooten Over a year ago

So it can be ran with 0-4 arguments? simply separated with commas?

Matthias Over a year ago

To make it short: Yes.

David Heffernan · Accepted Answer · 2014-02-10 10:13:48Z

2

The use of [] indicates that the enclosed parameter is optional and can be omitted.

answered Feb 10, 2014 at 10:13

David Heffernan

616k46 gold badges1.1k silver badges1.5k bronze badges

Collectives™ on Stack Overflow

How to read typical function documentation in Python?

3 Answers 3

1 Comment

2 Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

1 Comment

2 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related