GeezerVison is showing github.com — documentation for function arguments · Issue #91485 · python/cpython
documentation for function arguments #91485Descriptionit 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
Activityeugenetriguba commented on Apr 13, 2022 vainaixr commented on Apr 13, 2022 ContributorAuthor More actions i meant the meaning of the arguments, like the *[, i do not know if there are more variations to that. JulienPalard commented on Apr 13, 2022 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? Reacted by Jelle Zijlstra vainaixr commented on Apr 13, 2022 ContributorAuthor More actions yes, thanks for the explanation added a commit that references this issue on Oct 15, 2022gh-91485: Doc: Using Python syntax to document builtin Python functio… added a commit that references this issue on Oct 15, 2022gh-91485: Doc: Using Python syntax to document builtin Python functio… added a commit that references this issue on Oct 22, 2022gh-91485: Doc: Using Python syntax to document builtin Python functio… hauntsaninja commented on Jan 20, 2023 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 commented on Jan 21, 2023
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)- ...
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|