| msg305525 - (view) |
Author: STINNER Victor (vstinner) *  |
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: PyDoc_STRVAR(os_dup__doc__, "dup($module, fd, /)\n" "--\n" "\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) * |
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 select.select() 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) * |
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: PyDoc_STRVAR(builtin_chr__doc__, "chr($module, i, /)\n" "--\n" "\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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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?" https://mail.python.org/pipermail/python-dev/2017-November/150233.html |
|
|
| msg305658 - (view) |
Author: Tal Einat (taleinat) * |
Date: 2017-11-06 16:59 |
| My apologies, I seem to have been the source of the confusion. I misunderstood your original meaning. |
|
|