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: `function(mandatory_argument[, optional_argument]` represents an optional
argument that will alter the function if provided. In the [`iter()`
documentation](https://docs.python.org/3.4/library/functions.html#iter):

> 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](https://docs.python.org/3.4/library/functions.html#bytearray)):

    
    
    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__`](https://docs.python.org/3.3/library/functions.html#__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](https://github.com/python-
git/python/blob/master/Python/bltinmodule.c#L1274) 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)
    

