How to communicate the philosophy of type annotations in Python?

[willingc]

A question from the Typing summit:

How to communicate the philosophy of type annotations in Python?

• Beginners don't need annotations
• "Catching bugs" is how to sell it to your engineering director :-)
• Adding improvements like new Union to simplify the syntax

There's a nice community around typing that is responsive to ideas and thoughts.

[carljm]

Thank you so much Carol for kicking off this discussion! It's super important.

I think sometimes we fall into the trap of thinking that proposals to change Python in order to allow for more ergonomic type annotations are "changing Python just for the typing people" and are harmful to non-typing users. I think this is actually backwards and it's important to reframe this tension. Typing is here to stay, and sooner or later people who start without type annotations (which is great!) will need to read annotated code, too. If we can make type annotations simpler, more ergonomic, better "fit" into the language, and easier to read, this doesn't just benefit active users of typing -- it perhaps has the most benefit for non-users of typing who still have to read annotated code in other peoples' libraries!

So I think the idea I've heard suggested that we need to "split" the language so typed Python can add syntax without affecting untyped Python is not the right direction. We all have to read each others' code, so the thing that benefits everyone, users of types and non-users of types, is to better integrate and streamline type annotations (without ever requiring them, which should go without saying.)

[stefanv]

Having some evidence for the benefits of annotation would be helpful in convincing projects to adopt it. Many Python projects are very strong on the testing front partially because of the lack of static type checking, but it also means that the benefits of adding annotations are less evident.

In numpydoc types are specified inline; I think we'd benefit from having those be grabbed from annotations instead.

@carljm Fully agree with your sentiment above: "sooner or later..." — keeping it simple is beneficial for all Python users, preserving one of Python's best features: its ease of readability.

[willingc]

Newer developer sees a type annotation

• Don't panic
• How to read documentation
• Why someone would use the TA
  • Like unit tests, it improves code quality
• It's okay as a new developer to be aware of TA but feel no pressure to use until you are creating production code at scale

[willingc]

TODO: SciPy sprint for Carpentries lesson re: typing esp. tensors as a compelling use case; code quality; reproducibility; scaling. Reach out to Turing Way too.

[shannonzhu]

Thanks Carol for starting a discussion here!

I'm interested in getting the ball rolling on some centralized documentation for the Python type system, which ideally could also include some opening or introductory pages that discuss things you just mentioned like (1) how to read documentation, (2) why someone might want to use type annotations, why this is particularly helpful for coding at scale, etc.

Right now it's a bit difficult to find any source of truth for learning about the type system outside of finding disjoint pieces scattered across PEPs, or picking a type checker and going to read their website. If we can get a documentation source that the larger Python community has contributed to and agrees on, I could see this providing a lot of value to new and existing users of types in the language.

I recall there was a suggestion during the summit to get this started as a subdirectory of the typing repository, where we can incrementally iterate, then potentially moving this to somewhere discoverable alongside other python documentation.

Thoughts? I also plan to start some discussion on this in the typing sig mailing list.

[encukou]

I recall there was a suggestion during the summit to get this started as a subdirectory of the typing repository, where we can incrementally iterate, then potentially moving this to somewhere discoverable alongside other python documentation.

AFAICS, this was started in typing docs.

[hauntsaninja]

Note the specific section linked is specifically aimed at library authors considering whether to ship type hints to their users via PEP 561.

We should add more docs to typing.readthedocs.io to address more user profiles.