New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support return annotation in signature for Argument Clinic #76120
Comments
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]
Return a duplicate of a file descriptor. Currently, Argument Clinic generates: PyDoc_STRVAR(os_dup__doc__, 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))" 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. |
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. |
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]
Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff. Argument Clinic generates: PyDoc_STRVAR(builtin_chr__doc__, 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. |
I am not asking for a full support of return type annotation. Just export |
Currently nothing is supported Argument Clinic. Return converters don't contain information that can be used in return type annotation. |
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. |
I believe we currently have a policy that the python standard library will not include type annotations, that those are provided by typeshed. |
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. |
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. |
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?" |
My apologies, I seem to have been the source of the confusion. I misunderstood your original meaning. |
I don't have the bandwidth to work on this issue, it's inactive for 5 years, I close it. |
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:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: