2

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

svenhalvorson
  • 1,090
  • 8
  • 21
  • You can see that you can pass function name (e.g. add_two_number or whatever) as the first argument. Please see this url. https://realpython.com/python-reduce-function/#:~:text=Python's%20reduce()%20is%20a,to%20a%20single%20cumulative%20value. – pullidea-dev May 26 '21 at 15:45

4 Answers4

2

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.

rawrex
  • 4,044
  • 2
  • 8
  • 24
2

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
S.B
  • 13,077
  • 10
  • 22
  • 49
  • That is very strange looking to me but I appreciate the answer. I assume that from your description `fn(10, 20, 30)` would not be acceptable – svenhalvorson May 26 '21 at 17:40
  • @svenhalvorson exactly because, `c` hast to be keyword argument. – S.B May 26 '21 at 18:30
1

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

Fonzie
  • 186
  • 1
  • 4
-1

Is this what you need?

reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])
kolja
  • 164
  • 7
  • 2
    They aren't asking how to use `reduce`, they're asking how to interpret documentation in the general case with `reduce` being used as an example. – Kemp May 26 '21 at 15:42
  • If a person reads the whole docstring it should be obvious what "function" and "sequence" mean. I'm still not sure what's the problem. – kolja May 26 '21 at 15:48
  • 1
    The question was "how can you determine from the docstring whether a function expects positional or keyword arguments", with `reduce` given as an example of a function with a docstring that doesn't seem to specify but an implementation that requires one type. It's not about `reduce` specifically or the meaning of `reduce`'s arguments. – Kemp May 26 '21 at 16:07