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

Brett Cannon brett at python.org
Mon Nov 6 13:37:03 EST 2017

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.timens() (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>

More information about the Python-Dev mailing list