[Python-Dev] Allow annotations using basic types in the stdlib?

[Victor Stinner]

Hi,

While discussions on the typing module are still hot, what do you
think of allowing annotations in the standard libraries, but limited
to a few basic types:

* None
* bool, int, float, complex
* bytes, bytearray
* str

I'm not sure about container types like tuple, list, dict, set,
frozenset. If we allow them, some developers may want to describe the
container content, like List[int] or Dict[int, str].

My intent is to enhance the builtin documentation of functions of the
standard library including functions implemented in C. For example,
it's well known that id(obj) returns an integer. So I expect a
signature like:

  id(obj) -> int


Context: Tal Einat proposed a change to convert the select module to
Argument Clinic:

   https://bugs.python.org/issue31938
   https://github.com/python/cpython/pull/4265

The docstring currently documents the return like:
---
haypo at selma$ pydoc3 select.epoll.fileno|cat
Help on method_descriptor in select.epoll:

select.epoll.fileno = fileno(...)
    fileno() -> int

    Return the epoll control file descriptor.
---

I'm talking about "-> int", nice way to document that the function
returns an integer.

Problem: even if Argument Clinic supports "return converters" like
"int", it doesn't generate a docstring with the return type. So I
created the issue:

"Support return annotation in signature for Argument Clinic"
https://bugs.python.org/issue31939

But now I am confused between docstrings, Argument Clinic, "return
converters", "signature" and "annotations"...

R. David Murray reminded me the current policy:

"the python standard library will not include type annotations, that
those are provided by typeshed."

While we are discussing removing (or not) typing from the stdlib (!),
I propose to allow annotations in the stdlib, *but* only limited to
the most basic types.

Such annotations *shouldn't* have a significant impact on performances
(startup time) or memory footprint.

The expected drawback is that users can be surprised that some
functions get annotations, while others don't. For example,
os.fspath() requires a complex annotation which needs the typing
module and is currently done in typeshed, whereas id(obj) can get its
return type documented ("-> int").

What do you think?

Victor