CourtBouillon

There are a lot of different questions and remarks behind this topic, so we built a short list to ask and answer some of them.

Type annotations are used everywhere, aren’t they standard?

There’s a hype, for sure: Python types are really everywhere, all the new projects use them, everybody agrees. That’s a standard now!

Well… That’s not 100% true. Actually, they’re not everywhere.

The code sample on Python’s front page doesn’t have type annotations. Most of the samples in the documentation don’t have annotations. And most of the standard library doesn’t have annotations.

So, annotations may be very popular among Python developers who talk about it, with a lot of arguments about how they’re cool. But they may not be popular for people who don’t talk about them. As a consequence: most of the content we read about annotations is about the good parts, by people who use them, or want to share the popular opinion that they love them. It’s easy to think that everybody loves annotations, use them, or should at least use them.

But we have a different feeling when talking with people in conferences.

It’s hard to have real metrics about how many projects have annotations, that would be interesting to know!

Having type hints is better than not having them! Samples in documentation are just useful to learn Python!

If they’re "just" omitted for Python newcomers, there’s a reason.

Thinking about types adds some unnecessary work. We may argue that it’s useful, and we will in this article, but we can’t forget this point: type hints don’t change anything during code execution, you get exactly the same result with or without. They’re not necessary.

Annotations add a layer of complexity. That’s one more thing to think about when coding. That’s hard for newcomers, because they already have to take care of topics that are necessary when coding: syntax, logic, algorithms, architecture, etc.

This level of complexity also exists when reading code. Adding type hints obviously adds words to read, to understand, to process. Of course, these words can be interested to understand what a variable is. So there’s a balance to find, and this balance is not the same for everybody.

What we prefer to do is to find good variable names, that explains what the variable is, when possible.

We also like to add typing information in docstrings. These types can be a bit simpler, but technically less correct than real type hints that would actually be checked. We think that they’re a good way to advertise about the safe way to use the API, without 100% preventing users from using other types when they know what they do.

Because, let’s admit it: we love Python’s dynamic typing system. And we love to use it, even if it looks messy or wrong for some people.

Don’t Type Annotations Prevent Bugs? Quality Matters!

During many months, I did work on Python projects with type hints. And I found type hints amazing.

This project had 100% coverage for types and tests. Everything was documented, commented, with a great architecture. That was impressive.

What I adored with type hints was the feeling of creating code that was "right". Thinking really hard about types, creating dedicated classes for everything, removing ambiguity with subtle abstraction layers, adding smart architecture tricks, and finally getting my 100% coverage reward when launching MyPy… What a great feeling! And I was really proud of what I did, because my code was "right". I was really proud, because I was solving complex typing problems and finding very brilliant solutions.

But… After a few weeks, one question came: why? 🤔

That was a hard question. Solving complex problems, finding brilliant solutions, adding smart architecture tricks… What a rewarding job for me! I’m an engineer, I can talk with my friends how complex my code is, and get social reward from this situation.

I was happy. The people I worked for were happy. Did it really help the project? I don’t think so.

At the end of my mission, I had to admit that a large part of my work had been spent solving complex problems about code architecture, types, abstractions. But the code could have been way shorter, way simpler, with the same features, with the same tests passing.

Complexity is socially rewarded, simplicity is not. My engineer friends are not impressed by simplicity. My family is not impressed by simplicity. My clients are not impressed by simplicity.

At the end, my true, real feelings were:

• I could have implemented the same features with less code, and the same level of quality.
• I solved a lot of "problems" that were theoretical, not real bugs.
• There’s no typing problem that can’t be caught by a test, but tests cover way more things that type hints.
• The client was happy because I was smart. It would have been smarter to avoid that useless work.

Static typing comes with great advantages

Yes, that’s true. But Python is a dynamically typed language, even with type hints 🦆.

When a language is statically typed, users can often get powerful features. Rust 🦀, for example, provides a very smart typing system: it brings type checks, avoids inconsistencies, and optimizes speed, just as most statically typed languages. It can even manage memory in a really efficient way, handle concurrency, and give unprecedented security thanks to the way the language is designed.

Writing Rust is hard, but you know what you get: impressive runtime benefits.

But type hints in Python bring no runtime benefits. At all. Then… Why should we solve all the problems static typing forces us to solve, without getting anything at runtime?

If we ever decide to add type hints, we should probably use a language that brings full power out of it, not just a small part of it.

Much less people will contribute without type hints!

Maybe much less people would contribute with type hints. And we’re already two of them ☺️.

IDEs and AI are powerful for users, they need annotations!

We know that a lot of people love type hints. And we don’t want to convince them that annotations are wrong. We understand that they really would prefer to have them.

We’d really like to have annotations for the people who use our libraries. But not in our repositories.

A solution would be to contribute to Typeshed. This way, users could have type checks with their favorite tools, and we wouldn’t have to maintain them. We know that it may not be a perfect solution for some users, but that would be at least a start, and cover many use cases already.

Come on, type hints wouldn’t be hard to maintain!

Then, please, contribute to Typeshed!

Sorry, but I don’t have enough time or skills to maintain a module…

We know, it’s hard to maintain a module with quite a lot of activity, it takes time and is a long-term commitment. Don’t believe those who say that "it’s not hard to maintain" ☺️.

But that’s a good way to become a contributor. And you’re not alone, you’ll find other great contributors to help you on the way. 🫶 Don’t be shy, just try! 🫶