Explanation of Python doc argument syntax

Question

Is anyone able to help me to understand the syntax of arguments being passed to some methods in the Python doc?

Examples of the type of things that are confusing me would be from the iter() function

iter(o[, sentinel])

From my understanding this is equivalent to

iter(o, sentinel)

but as to why I really don't understand.

Answer 1

function(mandatory_argument[, optional_argument] represents an optional argument that will alter the function if provided. In the iter() documentation :

The first argument is interpreted very differently depending on the presence of the second argument.

In what way optional arguments alters the function should be described in the documentation to it.

Optional arguments can be nested, so you may see something like ( source ):

bytearray([source[, encoding[, errors]]])

That means that each of the arguments are optional, but builtin upon the previous ones. So the following are all valid calls:

bytearray(source)
bytearray(source, encoding)
bytearray(source, encoding, errors)

But this is not:

bytearray(source, errors=errors)

There is a second way to indicate that arguments are optional:

__import__(name, globals=None, locals=None, fromlist=(), level=0)

This tells us that all these arguments (but name) are optional and also tells us the default for when we do not provide arguments for them.

On the code site in pure python you can get optional arguments by:

def iter(o, sentinel=None):
    [do something]

But this would not be documented the way above, as we can see in the example of __import__ :

__import__(name, globals=None, locals=None, fromlist=(), level=0)

To see why iter is different read the section at the end of my post.

Also note that in the example of the iter() builtin you can not provide sentinel as keyword argument and trying will raise a TypeError:

>>> iter([], sentinel=None)
Traceback (most recent call last):
   File '<stdin>', line1, in <module>
TypeError: iter() takes no keyword arguments

in other cases though it may be possible:

>>> bytearray('', encoding='UTF-8')
bytearray(b'')

It is still true that providing a later argument without the previous ones will raise an error.

>>> bytearray('', errors='')
Traceback (most recent call last):
  File '<stdin>', line 1, in <module>
TypeError: string argument without an encoding

The "keyword like syntax" is the "normal" way to document optional arguments in python. Why is iter different? iter is a builtin and not implemented in python but in C. If we look at the source code of it we see that it treats the arguments as a tuple that may have one or two arguments.

builtin_iter(PyObject *self, PyObject *args)
{
    PyObject *v, *w = NULL;

    if (!PyArg_UnpackTuple(args, "iter", 1, 2, &v, &w))
        return NULL;
    if (w == NULL)
        return PyObject_GetIter(v);
    if (!PyCallable_Check(v)) {
        PyErr_SetString(PyExc_TypeError,
                "iter(v, w): v must be callable");
        return NULL;
    }
    return PyCallIter_New(v, w);
}

This might explain the "list-like syntax". It seems that the [optional_argument] notation is only used in modules that are programmed in C. For the normal user it makes no difference if there is

function([optional_argument])

or

function(optional_argument=True)

Answer 2

Brackets means that the argument in question is optional.

iter(o[, sentinel])

Ie the above example means that iter is a function which takes one mandatory argument o and one optional argument sentinel .

This means that you can call this function like this:

iter(o)  # Method 1

or like this:

iter(o, sentinel)  # Method 2

The behavior of the function depending on if you use method 1 or 2 is described by the text in the docs:

Return an iterator object. The first argument is interpreted very differently depending on the presence of the second argument. Without a second argument, o must be a collection object which supports the iteration protocol (the iter () method), or it must support the sequence protocol (the getitem () method with integer arguments starting at 0). If it does not support either of those protocols, TypeError is raised. If the second argument, sentinel, is given, then o must be a callable object. The iterator created in this case will call o with no arguments for each call to its next() method; if the value returned is equal to sentinel, StopIteration will be raised, otherwise the value will be returned.