[Python-Dev] Allow annotations using basic types in the stdlib? (original) (raw)

Victor Stinner victor.stinner at gmail.com
Mon Nov 6 11:02:54 EST 2017

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:

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

More information about the Python-Dev mailing list