Repository navigation
Help text of builtin functions – missing signatures #107526
Description
Activity
Yes, this is because of
NULLdefault :(arg: object = NULLIs there any way to fix it?
I've submitted https://discuss.python.org/t/ac-null-defaults-prevent-correct-signatures-lets-add-inspect-unrepresentable-to-fix-this/30753
I wanted to do it for quite a long time, sorry for ignoring this item in my backlog :)
Reacted by Lumír 'Frenzy' BalharIs this feasible for 3.11?
If not, should we add the signatures to the doc text manually, in these cases where AC doesn't generate anything?FWIW, this breaks Jedi, which currently parses the manually-formatted signatures in docstrings: davidhalter/jedi#1952
They would be happy to move toinspect.signatureonce that works. Until it does, parsing__doc__seems like a sensible workaround, so this might be considered a regression.
So I'm flagging this as a potential blocker.1 remaining item
I meant 3.12, not 3.11. Got my version numbers mixed up, sorry!
The fix @sobolevn proposes doesn't seem feasible for 3.12, as it requires introducing a new object in the
inspectmodule. As a less invasive fix, maybe we can directly add these signatures to the docstrings?Reacted by sobolevn and Petr Viktorin@JelleZijlstra that's exactly what I am proposing for 3.11 and 3.12 in #107526 (comment) :)
Reacted by Jelle ZijlstraOk, I think that we would need to revert these changes. Here's why:
- We cannot simply add signatures back in AC. Here's what is generated:
/*[clinic input] dir as builtin_dir arg: object = NULL / dir([object]) -> list of strings Show attributes of an object. ... [clinic start generated code]*/ static PyObject * builtin_dir_impl(PyObject *module, PyObject *arg) /*[clinic end generated code: output=24f2c7a52c1e3b08 input=2e2cb290445c88f3]*/
outputs:
PyDoc_STRVAR(builtin_dir__doc__, "dir($module, arg=<unrepresentable>, /)\n" "--\n" "\n" "dir([object]) -> list of strings\n" "\n" "Show attributes of an object.\n" "\n" "...");
But, that's not what we want!
- Argument clinic has
only_docstringoption for functions, but I will need to rework how it sets this value toTrueto be able to use it. This would require extra testing and stuff - I hope that https://discuss.python.org/t/ac-null-defaults-prevent-correct-signatures-lets-add-inspect-unrepresentable-to-fix-this/30753 will land for new code, so I won't have to change the clinic code
FYI I don't think the effects on Jedi are extreme (speaking as its author). It's just that it's a bit unfortunate that the signatures won't be shown anymore in that case for 3.12. So yes, it's a regression, but not a problematic regression. So if argument clinic helps you here with other issues, it might just be worth keeping it. IMO the more problematic change here might be that the docstrings are just not as good as they were previously. Especially for
iterthe docstring talks aboutIn the first form, [...]. What is the first form? In the other docstrings there are weird comments as well.In the end it would be really nice if these functions were eventually supported by
inspect.signature, but I don't think you need to hurry there either.Reacted by Tomas R.#107782 can help.
Reacted by Erlend E. Aasland- added a commit that references this issue
on Aug 21, 2023 The immediate issue was fixed here. We still have the broader issue that
inspect.signaturecan't handle `', but that's tracked in #87233.- moved this from Todo to Done in Release and Deferred blockers 🚫
on Nov 9, 2023
I don't understand the deep details here but I think something went wrong in commit bdfb694 when some of the builtin functions where transferred to argument clinic.
The problem I see is in the help texts of those functions. Here are a few examples of
help(<function>):iter
Python 3.11.4
Python 3.12.0b4
As you can see, the help in 3.12 is talking about two forms but there are no signatures so it doesn't make sense.
next
Python 3.11.4
Python 3.12.0b4
Again, the help text talks about
iteratoranddefaultbut missing signature means that the reader might not know what those are.getattr
Python 3.11.4
Python 3.12.0b4
Again, a similar case here.
Linked PRs