In this lesson, you’ll explore the pros and cons of type hints. In the previous lesson, you took a peek into what type checking in Python looks like. Here are some of the advantages of type hints:

Type hints help catch certain errors, as you saw in the previous lesson.
Type hints help document your code. Traditionally, you would use docstrings if you wanted to document the expected types of a function’s arguments. This works, but as there is no standard for docstrings (despite PEP 257), they can’t be easily used for automatic checks.
Type hints improve IDEs and linters. They make it much easier to statically reason about your code.
Type hints help you build and maintain a cleaner architecture. The act of writing type hints forces you to think about the types in your program. While the dynamic nature of Python is one of its great assets, being conscious about relying on duck typing, overloaded methods, or multiple return types is a good thing.

Of course, static type checking is not all peaches and cream. There are also some downside you should consider:

Type hints take developer time and effort to add. Even though it probably pays off in spending less time debugging, you will spend more time entering code.
Type hints work best in modern Pythons. Annotations were introduced in Python 3.0, and it’s possible to use type comments in Python 2.7. Still, improvements like variable annotations and postponed evaluation of type hints mean that you’ll have a better experience doing type checks using Python 3.6 or even Python 3.7.
Type hints introduce a slight penalty in start-up time. If you need to use the typing module, then the import time may be significant, especially in short scripts.

Should you use static type checking in your own code? It’s not an all-or-nothing question. Python supports the concept of gradual typing. This means that you can gradually introduce types into your code. Code without type hints will be ignored by the static type checker. Therefore, you can start adding types to critical components, and continue as long as it adds value to you.

Here are a few rules of thumb on whether to add types to your project:

If you’re just beginning to learn Python, you can safely wait with type hints until you have more experience.
Type hints add little value in short throwaway scripts.
In libraries that will be used by others, especially ones published on PyPI, type hints add a lot of value. Other code using your libraries needs these type hints to be properly type checked itself. For examples of projects using type hints, see cursive_re, black, our own Real Python Reader, and Mypy itself.
In bigger projects, type hints help you understand how types flow through your code, and are highly recommended, all the more so in projects where you cooperate with others.

In his excellent article The State of Type Hints in Python, Bernát Gábor recommends that “type hints should be used whenever unit tests are worth writing.” Indeed, type hints play a similar role as tests in your code: they help you as a developer write better code.

00:00 In this video, I’ll show you the pros and cons of type hints. What are some of the ways that type hints help? First, type hints can help you catch certain types of errors. This you already saw as we demonstrated Mypy in the last video and how it allows you to catch type errors in your own code.

00:17 Removing those errors goes a long way to helping you with debugging. Type hints help to document your code. Traditionally, you would use docstrings if you wanted to document the expected types of a function’s arguments.

00:31 This works as a documentation tool, but as there is no standard for docstrings, they can’t be easily used for automatic checking. Type hints also provide a certain amount of readability, in that they’re included right within the function as it’s written out.

00:49 This form of documentation is not only useful for yourself—and your future self—but especially if you’re going to share that project with a team or if it’s possibly going to be part of an open-source project. Type hints are going to improve the functionality inside of many IDEs and linters.

01:07 This will enhance the ability for that IDE to do code completion and for it to offer suggestions. You’ve seen this in a couple of different places, such as as I was showing you inside of PyCharm.

01:20 You might have also noticed it when I was using Visual Studio Code.

01:26 And even in the REPL replacement bpython, you might’ve noticed it.

01:32 Type hints also help you build and maintain a cleaner architecture. The act of writing these type hints forces you to think about the types in your program. While the dynamic nature of Python is one of its great assets, being conscious about relying on duck typing, overloaded methods, or multiple return types is a good thing!

01:52 So, what are some of the downsides of type hints? Well, it’s going to take you, as a developer, more time and effort to add these. In the end, it probably will pay off in spending less time debugging, but you will be spending more time entering in your code. Type hints work best in modern Python.

02:09 As you’ll see in an upcoming video, type comments were available in Python 2.7, but improvements like annotations were only introduced into Python 3, and the idea of using them for type hints is something that happened in 3.5, and more advanced features such as variable annotations and postponed evaluation work best in Python 3.6 or even 3.7.

02:31 There are links below this video to give you more information about those topics. Type hints introduce a slight penalty in start-up time, especially if importing the typing module. In general, it’s a small hit.

02:45 Something to keep in mind: Type hints are not an all-or-nothing deal. Python supports the concept of gradual typing. What that means is that as you’re writing your code, you can introduce your types as you go.