documentation for function arguments

[vainaixr]

it is confusing what these mean, is there a page which explains the difference between these, or if not, then could there be a page which explains the difference between these, (and more variations)

max(iterable, *[, key, default])
max(arg1, arg2, *args[, key])
iter(object[, sentinal])
input([prompt])
itertools.accumulate(iterable[, func, *, initial=None])

Linked PRs

• gh-91485: Avoid unnecessary use of non-Python syntax in io docs #101177
• [3.11] gh-91485: Avoid unnecessary use of non-Python syntax in io docs (GH-101177) #101199
• [3.10] gh-91485: Avoid unnecessary use of non-Python syntax in io docs (GH-101177) #101200

[eugenetriguba]

https://docs.python.org/3/library/functions.html
https://docs.python.org/3/library/itertools.html#itertools.accumulate

I'm assuming these are what you're referring to?

[vainaixr]

i meant the meaning of the arguments, like the *[, i do not know if there are more variations to that.

[JulienPalard]

Maybe the function docs could be made easier to read by sticking to Python syntax?

As / and * are valid in Python syntax, I can easily imagine a newcomer thinking that *[ is valid too (it may be the case here).

By sticking to valid Python syntax (reminds me of the repr philosophy) developers would read them more easily, maybe, but it means lots of None, like:

max(iterable, *[, key, default])  →  max(iterable, *, key=None, default=None)
max(arg1, arg2, *args[, key])  →  max(arg1, arg2, *args, key=None)
iter(object[, sentinal])  →  iter(object, sentinel=None, /)
input([prompt])  →  input(prompt='', /)
itertools.accumulate(iterable[, func, *, initial=None])  →  itertools.accumulate(iterable, func=None, *, initial=None)

It would mean checking if that's actually true that they expect None as the default value, they may expect a sentinel value. Typically here for input the default value is the empty string, not None.

In case like range where there's no clean way to describe the function using Python, or for functions expecting a sentinel to tell if they received the value or not, we could just list alternative calls, as we actually do for range, like:

class range(stop)
class range(start, stop, step=1)

does my rewritings helps you understand, @vainaijr?

[vainaixr]

yes, thanks for the explanation

[hauntsaninja]

I agree that we should try and stick to using Python syntax where possible.

Grepping Doc/ for *[ I found a couple uses, however only the one in io has documentable default values #101177 . So after that is merged, I will close this issue since there's a larger discussion to be had about how to document those kinds of functions (e.g. maybe use ... as the default value?). E.g. see python/devguide#1020

[arhadthedev]

max(iterable, *[, key, default]) → max(iterable, *, key=None, default=None)

Previously I've thought that *[...] means "an optional group that can be repeated". For "optional named-only arguments" I would expect *, [...].

In other words, I would parse max(iterable, *[, key, default]) as:

• max(iterable)
• max(iterable, key, default)
• max(iterable, key1, default1, key2, default2)
• ...