This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Support return annotation in signature for Argument Clinic
Type: enhancement Stage:
Components: Argument Clinic Versions: Python 3.7
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: brett.cannon, larry, ncoghlan, r.david.murray, serhiy.storchaka, taleinat, vstinner
Priority: normal Keywords:

Created on 2017-11-03 23:31 by vstinner, last changed 2022-04-11 14:58 by admin.

Messages (11)
msg305525 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-11-03 23:31
Argument Clinic supports a few return types like NoneType, int, bool, etc. But the return type is omitted in the private docstring used to build the __text_signature__, finally used to build a Signature object in inspect.signature().

For example, os.dup() is declared in Modules/posixmodule.c with:

/*[clinic input]
os.dup -> int

    fd: int

Return a duplicate of a file descriptor.
[clinic start generated code]*/

Currently, Argument Clinic generates:

"dup($module, fd, /)\n"
"Return a duplicate of a file descriptor.");

The return type is omitted in the first line.

Finally, the return type is not documented in the signature:

haypo@selma$ ./python -c "import os,inspect; print(inspect.signature(os.dup))"
(fd, /)

I noticed this limitation while reviewing the PR 4265 which converts the select module to Argument Clinic. Previously, the return type like "-> None" or "-> int" was documented. With Argument Clinic, it's not documented nor generated in the signature, the information is lost.
msg305557 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2017-11-04 13:08
I'm not sure that the current concept of return converters in AC is can be used for specifying return value annotations.

For example, what if I want to annotate the return value type with using a return converter?

Another example: The current doc-string for begins with:

select(rlist, wlist, xlist[, timeout]) -> (rlist, wlist, xlist)

I can't see how describing the return type being a 3-tuple of lists would work with return converters.
msg305560 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-11-04 13:27
Argument Clinic doesn't have any relations to annotations. It is just by accident use the syntax similar to the syntax  of annotations in its declarations (and actually use Python parser for parsing them as anotations, but this is an implementation detail). It doesn't set argument annotations in signatures.

For example, chr() is declared with:

/*[clinic input]
chr as builtin_chr

    i: int

Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff.
[clinic start generated code]*/

Argument Clinic generates:

"chr($module, i, /)\n"
"Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff.");

I think it could be possible to make Argument Clinic generating argument annotations basing on the accepted by converters types, but we are far from this.
msg305563 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-11-04 18:10
I am not asking for a full support of return type annotation. Just export
what is already supported in AC, export it in the signature.
msg305564 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-11-04 18:21
Currently nothing is supported Argument Clinic. Return converters don't contain information that can be used in return type annotation.
msg305592 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2017-11-05 11:31
Argument Clinic currently doesn't support input parameter type annotations either, though for this it has more relevant information in many cases.

I think it would be a great boon for AC to enable declaring type annotations, both for input parameters and for return values.
msg305600 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-11-05 16:05
I believe we currently have a policy that the python standard library will not include type annotations, that those are provided by typeshed.
msg305606 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2017-11-05 17:58
R. David is correct that currently the policy is there are no type hints in the stdlib. Now the interesting thing about AC is the type hint info could be kept just in the docstring and not added to __annotations__ which somewhat goes around this restriction. Plus I think Victor is only talking about the docstring ATM anyway.
msg305608 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-11-05 18:45
Victor is talking about inspect.signature(). In Python 3.5+ the result is "(fd, /)". In older versions it raises a ValueError. The docstring in 3.4 is 'dup(fd) -> fd2\n\nReturn a duplicate of a file descriptor.' It doesn't contain information that dup() returns int. It contains implicit information that dup() perhaps returns other file descriptor, but this is already explicitly documented by words. I don't see a loss of information here.
msg305649 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2017-11-06 16:12
I'm sorry, I'm confused between docstrings and annotations.

My first goal is to not loose the return type from the docstring when the select module is converted to Argument Clinic, at least for the simplest return types. Complex return types can be documented manually in the body of a docstring.

Return *annotation* would be nice to have, but it seems to be opposed to the current policy. I started a discussion on python-dev to ask if we should modify this policy :-)

"[Python-Dev] Allow annotations using basic types in the stdlib?"
msg305658 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2017-11-06 16:59
My apologies, I seem to have been the source of the confusion. I misunderstood your original meaning.
Date User Action Args
2022-04-11 14:58:54adminsetgithub: 76120
2017-11-06 16:59:38yselivanovsetnosy: - yselivanov
2017-11-06 16:59:14taleinatsetmessages: + msg305658
2017-11-06 16:12:43vstinnersetmessages: + msg305649
2017-11-05 18:45:36serhiy.storchakasetmessages: + msg305608
2017-11-05 17:58:02brett.cannonsetmessages: + msg305606
2017-11-05 16:05:04r.david.murraysetnosy: + r.david.murray
messages: + msg305600
2017-11-05 11:31:40taleinatsetmessages: + msg305592
2017-11-04 18:21:55serhiy.storchakasetmessages: + msg305564
2017-11-04 18:10:32vstinnersetmessages: + msg305563
2017-11-04 13:27:13serhiy.storchakasetmessages: + msg305560
2017-11-04 13:08:22taleinatsetnosy: + taleinat
messages: + msg305557
components: + Argument Clinic
2017-11-03 23:31:32vstinnercreate