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

Victor Stinner victor.stinner at gmail.com
Mon Nov 6 11:07:38 EST 2017

Related to annotations, are you ok to annotate basic types in the documentation and/or docstrings of the standard library?

For example, I chose to document the return type of time.time() (int) and time.time_ns() (float). It's short and I like how it's formatted. See the current rendered documentation:

https://docs.python.org/dev/library/time.html#time.time

"Annotations" in the documentation and docstrings have no impact on Python runtime performance. Annotations in docstrings makes them a few characters longer and so impact the memory footprint, but I consider that the overhead is negligible, especially when using python3 -OO.

Victor

2017-11-06 17:02 GMT+01:00 Victor Stinner <victor.stinner at gmail.com>:

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 methoddescriptor 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