anext builtin docstring has no signature text or info about default argument

[eriknw]

BPO	43918
Nosy	@gvanrossum, @terryjreedy, @eriknw, @pablogsal
PRs	bpo-43918: document signature and default argument of anext builtin #25551

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-04-23.03:30:06.398>
labels = ['interpreter-core', 'type-feature', '3.10']
title = 'anext builtin docstring has no signature text or info about default argument'
updated_at = <Date 2021-06-22.21:01:15.946>
user = 'https://proxy-ga.blitzz.co/proxy/123456/github.com/eriknw'

bugs.python.org fields:

activity = <Date 2021-06-22.21:01:15.946>
actor = 'gvanrossum'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Interpreter Core']
creation = <Date 2021-04-23.03:30:06.398>
creator = 'eriknw'
dependencies = []
files = []
hgrepos = []
issue_num = 43918
keywords = ['patch']
message_count = 4.0
messages = ['391650', '391828', '391839', '396363']
nosy_count = 4.0
nosy_names = ['gvanrossum', 'terry.reedy', 'eriknw', 'pablogsal']
pr_nums = ['25551']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://proxy-ga.blitzz.co/proxy/123456/bugs.python.org/issue43918'
versions = ['Python 3.10']

[eriknw]

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: #23847 (comment)

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

Related issue: https://proxy-ga.blitzz.co/proxy/123456/bugs.python.org/issue31861

(PR forthcoming)

[terryjreedy]

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.

[eriknw]

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 "" 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.

[gvanrossum]

New changeset 6af4e6b by Erik Welch in branch 'main':
bpo-43918: document signature and default argument of anext builtin (bpo-25551)
6af4e6b

[hauntsaninja]

Closing this as completed, since #25551 makes help(anext) better. Supporting signatures with C NULL default values in inspect.signature is a more general issue.