Knowing that functions do not accept named argument from docstring

user_7117061 0
Viewed 118

He ya'll,

I'm confused as to how I'm supposed to know whether a function can accept named arguments or not from the docstring. Here is an example:

from functools import reduce
?reduce

enter image description here

From this documentation, my instinct would be to use the function like this:

reduce(
   function = lambda x, y: x+y, 
   sequence = [1, 2, 3, 4, 5]
   )

However, we get :

enter image description here

How could I know this would happen from the docstring? Coming from another language, it seems like the documentation is telling me that the two arguemnts are called function and sequence.

Thanks

docstring python
4 Answers

In general, there are no strict rules for such (not to my knowledge). Documentation can't raise a syntax error :)

There is a marker, the *, that denote that all the arguments after it are keyword arguments only, it goes like this:

func(arg1, arg2, *, kwarg1, kwarg2)

Its use is not only in documentation, but in real callable functions. You can also incorporate it in your own definitions.

It's also common to have this pattern in a docstring:

func(arg1, arg2, arg3=default_value, **kwargs)
# kwarg_a: description of kwarg_a
# kwarg_b: description of kwarg_b
# kwarg_c: description of kwarg_c

So, there are some guidelines. Generally, we can assume that parameters are positional unless explicitly noted as being keyword (such as in your example with reduce). I recommend to check this answer for more info.

user_146247290

I don know why neither in document nor in "reduce" __docs__ , it doesn't indicate this. Generally by looking at signature is how you can tell the function doesn't accept keyword argument :

def fn(a, b, /):
    pass

Here is / as the last parameter in function's signature indicates that the parameters a and b have to be passed "positional". (because they are before /)

In addition we have * parameter which tells that next parameters after it should be passed as keyword argument.

You can mix them like:

def fn(a, /, b, *, c):
    pass

fn(10, 20, c=30)   # acceptable
fn(10, b=20, c=30) # acceptable
user_139445240

There's a difference in Python between "keyword arguments", "optional arguments" and "positional arguments".

An example of a function using them is (from python doc) : sorted(iterable, *, key=None, reverse=False)

Here the argument iterable is a positional argument, meaning that you just have to give your iterable to the function: it would be something like sorted(my_list). These arguments are mandatory.

The other parameters are called keyword arguments because they can be specified using the keyword. You can give only one of them if you'd like. If you don't specify the keyword, the order of arguments is the one given in the definition.

For instance if you want to sort a list in the reverse order, you'd write: sorted(my_list, reverse=True). Writing sorted(my_list, True) would not give you a list sorted in the reverse order.

Coming back to your example, your function accepts two positional parameters and an optional one (the optional one is not a keyword argument though). So you just need to write:
reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]).

PS: all positional arguments must be specified before using keyword arguments, otherwise it raises an error

user_66501320

Is this what you need?

reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])
user_25832490
Related