classification
Title: anext builtin docstring has no signature text or info about default argument
Type: enhancement Stage: patch review
Components: Interpreter Core Versions: Python 3.10
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: eriknw, gvanrossum, pablogsal, terry.reedy
Priority: normal Keywords: patch

Created on 2021-04-23 03:30 by eriknw, last changed 2021-06-22 21:01 by gvanrossum.

Pull Requests
URL Status Linked Edit
PR 25551 merged eriknw, 2021-04-23 03:41
Messages (4)
msg391650 - (view) Author: Erik Welch (eriknw) * Date: 2021-04-23 03:30
The new builtin `anext` does not have a signature (from `inspect.signature(anext)`).  This is expected, because `inspect` does not yet support signatures with C NULL default value.  However, `anext` also doesn't have text in its docstring that describes its signature as is typical for builtins.  This means `help(anext)` in the Python REPL gives no indication how to call the function.  It should.

This is clearly an oversight.  See comment here: https://github.com/python/cpython/pull/23847#commitcomment-45318696

Also, the "default" argument is not described in the docstring.

Related issue: https://bugs.python.org/issue31861

(PR forthcoming)
msg391828 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-04-25 00:56
inspect.signature(anext) raises "ValueError: <built-in function anext> builtin has invalid signature".  Guido, is this a bug?  Even if not, docstring should have it.
msg391839 - (view) Author: Erik Welch (eriknw) * Date: 2021-04-25 05:34
Thanks for taking a look Terry.  I saw that error as well.  It is separate from this issue, and I don't think it is a bug.  No other builtin functions or methods that raise this error with this text have such a notice in their docstring, so it doesn't seem appropriate to me to add it to the docstring at this point in time.

Search for "<unrepresentable>" to find other functions and methods that have the same issue.  `dict.pop` is one such example.

`inspect.signature(anext)` and `inspect.signature(next)` both raise ValueError.  The text for `next` is what one may hope to see (and why you raise a fair point): `"ValueError: no signature found for builtin <built-in function next>"`.  The difference between `anext` and `next` in this regard is that `anext` uses the argument clinic.  It is the argument clinic that converts `NULL` to `"<unrepresentable>"` in the signature text that inspect tries (and fails) to parse to get the AST of.

I actually did poke around a bit at having the the Argument Clinic and `inspect` module more intelligently pick up this case to give a better error.  I think this is doable, but should not be part of this bug report.
msg396363 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2021-06-22 21:01
New changeset 6af4e6b266cb19d646ad7e4051fc7974c3096d23 by Erik Welch in branch 'main':
bpo-43918: document signature and default argument of `anext` builtin (#25551)
https://github.com/python/cpython/commit/6af4e6b266cb19d646ad7e4051fc7974c3096d23
History
Date User Action Args
2021-06-22 21:01:15gvanrossumsetnosy: + gvanrossum
messages: + msg396363
2021-04-25 05:34:53eriknwsetmessages: + msg391839
2021-04-25 00:56:13terry.reedysetnosy: + terry.reedy
messages: + msg391828
2021-04-23 03:41:05eriknwsetkeywords: + patch
stage: patch review
pull_requests: + pull_request24271
2021-04-23 03:30:06eriknwcreate