13

I'm using type hints and mypy more and more. I however have some questions about when I should explicitly annotate a declaration, and when the type can be determined automatically by mypy.

Ex:

def assign_volume(self, volume: float) -> None:
    self._volume = volume * 1000

Should I write

self._volume: float = volume *1000

In this case?

Now if I have the following function:

def return_volume(self) -> float:
        return self._volume

and somewhere in my code:

my_volume = return_volume()

Should I write:

my_volume: float = return_volume()
1
  • I wouldn't do it in the first case. In the second case, could be okay. Commented Jul 6, 2018 at 13:29

3 Answers 3

16

Mypy (and PEP 484 in general) is designed so that in the most ideal case, you only need to add type annotations to the "boundaries" or "interfaces" of your code.

For example, you basically must add annotations/type metadata in the following places:

  1. The parameter and return types of functions and methods.
  2. Any object fields (assuming the types of your fields are not inferrable just by looking at your constructor)
  3. When you inherit a class. For example, if you specifically want to subclass a dict of ints to strs, you should do class MyClass(Dict[int, str]): ..., not class MyClass(dict): ....

These are all examples of "boundaries" of your code. Type hints on parameter/return types let the caller of the function make sure they're calling it correctly, type hints on fields let the caller know they're using the object correctly, etc...

Mypy (and other PEP 484 compliant tools) will then use that information and try to infer the types of everything else. This behavior is designed to roughly mimic how humans read code: once you know what types are being passed in, for example, it's usually pretty easy to understand what the rest of the code does.

After all, Python is a language that was designed from the start to be readable! We don't need to scatter type hints everywhere to enhance our understanding of what the code does.

Of course, mypy (and other PEP 484-compliant tools) aren't perfect, and sometimes they might not correctly infer what the type of some local variable will be. In that case, you might need to add a type hint to help mypy along. Ethan's answer gives a good overview of some common cases to watch out for. (Interestingly, these cases also tend to be examples of where a human reader might struggle to understand your code!)

So, to put everything together, the general recommendation is to:

  1. Add type hints to all of the "boundaries" of your code, like function parameters and return types.
  2. Default to not annotating variables. If mypy is unable to infer what type some variable should be, add an annotation to help it.
  3. If you find yourself needing to annotate lots of variables to make mypy happy, consider refactoring your code. If mypy is getting confused easily, a human reader is also likely to get confused easily.

So, to go back to your examples, you would not add type hints in either case. Both a human reader and mypy can tell that your _volume field must be a float: it's immediately obvious that must be the case since the parameter is a float and multiplying a float by an int will always produce another float.

Similarly, you would not add an annotation to your my_volume variable. Since return_volume() has type hints, it's trivially easy to see what type it's returning and understand that my_volume is of type float. (And if you make a mistake and accidentally think it's something other then a float, then mypy will catch that for you.)

0
10

Mypy does some pretty advanced type inference. Usually, you do not need to annotate variables. The mypy documentation [1] says this about inference:

Mypy considers the initial assignment as the definition of a variable. If you do not explicitly specify the type of the variable, mypy infers the type based on the static type of the value expression

The general rule of thumb then is "annotate variables whose types are not inferrable at their initial assignment".

Here are some examples:

  • Empty containers. If I define a as a = [], mypy will not know what types are valid in the list a.

  • Optional types. Oftentimes, if I define an Optional type, I will assign the variable to None. For example, if I do a = None, mypy will infer that a has type NoneType, if you want to assign a to 5 later on, you need to annotate it: a: Optional[int] = None.

  • Complex nested containers. For example, if you have a dictionary with both list and string values, mypy might, for example, infer Dict[str, Any]. You may need to annotate it to be more accurate.

Of course there are many more cases.

In your examples, mypy can infer the types of the expressions.

[1] https://mypy.readthedocs.io/en/latest/type_inference_and_annotations.html

3

For myself I started to write type hints everywhere, where it is possible. It isn't slower at all, and it makes it easier if you end up going back to your old code in the future. There is no negative aspect to using them as much as possible, except for increasing the size of your Python file.

1
  • Coming late to the party, but I hear you, bro
    – FaCoffee
    Commented Oct 20, 2022 at 10:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.