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

[Victor Stinner]

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