Repository navigation
documentation for function arguments #91485
Description
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])
Activity
eugenetriguba commentedon Apr 13, 2022
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 commentedon Apr 13, 2022
i meant the meaning of the arguments, like the
*[, i do not know if there are more variations to that.JulienPalard commentedon 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
reprphilosophy) developers would read them more easily, maybe, but it means lots ofNone, like: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
rangewhere 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:does my rewritings helps you understand, @vainaijr?
vainaixr commentedon Apr 13, 2022
yes, thanks for the explanation
pythongh-91485: Doc: Using Python syntax to document builtin Python f…
gh-91485: Doc: Using Python syntax to document builtin Python functio…
gh-91485: Doc: Using Python syntax to document builtin Python functio…
Revert "gh-91485: Doc: Using Python syntax to document builtin Python…
gh-91485: Doc: Using Python syntax to document builtin Python functio…
pythongh-91485: Avoid unnecessary use of non-Python syntax in io docs
hauntsaninja commentedon 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#1020gh-91485: Avoid unnecessary use of non-Python syntax in io docs (#101177
pythongh-91485: Avoid unnecessary use of non-Python syntax in io docs (…
pythongh-91485: Avoid unnecessary use of non-Python syntax in io docs (…
gh-91485: Avoid unnecessary use of non-Python syntax in io docs (GH-1…
gh-91485: Avoid unnecessary use of non-Python syntax in io docs (GH-1…
arhadthedev commentedon Jan 21, 2023
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)