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

[Brett Cannon]

On Mon, Nov 6, 2017, 10:27 R. David Murray, <rdmurray at bitdance.com> wrote:

> I agree with Steve.  There is *cognitive* overhead to type annotations.
> I find that they make Python code harder to read and understand.  So I
> object to them in the documentation and docstrings as well.  (Note:
> while I agree that the notation is compact for the simple types, the
> fact that it would appear for some signatures and not for others is a
> show stopper from my point of view...consistency is important to reducing
> the cognitive overhead of reading the docs.)
>
> I'm dealing with the spread of annotations on my current project,
> having to ask programmers on the team to delete annotations that they've
> "helpfully" added that to my mind serve no purpose on a project of the
> size we're developing, where we aren't using static analysis for anything.
>

I think this is the key point in your situation if the project is private.


> Maybe I'm being a curmudgeon standing in the way of progress, but I'm
> pretty sure there are a number of people in my camp :)
>

The key thing here is there are people like me who are using your analyzers
(and you are as well indirectly since the CLA bot is fully type hinted 😁).
I think the key question is whether we expect typeshed to keep up with
richer annotations using typing or are basic ones in the stdlib going ot
leave less of a gap in support in the long-term?

To be honest, I suspect most Python code in the stdlib would require
protocols to be accurate (C code is another matter), but return type hints
could be reasonably accurate.

-Brett


> On Mon, 06 Nov 2017 16:22:23 +0000, Steve Holden <steve at holdenweb.com>
> wrote:
> > 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.
> _______________________________________________
> 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/brett%40python.org
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20171106/aaccaee1/attachment.html>