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

[Steve Holden]

While I appreciate the value of annotations I think that *any* addition of
them to the stdlib would complicate an important learning resource
unnecessarily. S

Steve Holden

On Mon, Nov 6, 2017 at 4:07 PM, Victor Stinner <victor.stinner at gmail.com>
wrote:

> 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
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> https://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: https://mail.python.org/mailman/options/python-dev/
> steve%40holdenweb.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20171106/3a6096cc/attachment.html>