Python Typing Module

An Introduction to the Typing Module

The typing module is introduced in Python version 3.5 and used to provide hinting method types in order to support static type checkers and linters precisely predict errors.

Since Python has to determine the object type during the execution period, it occasionally becomes harder for developers in order to check the insides of the code.

According to the statistics, even the External Type Checkers, such as PyCharm IDE, do not yield the most acceptable outputs; only fifty percent of the error predictions are correct on average.

In order to mitigate the problem, Python introduces the concept of type hinting (also known as type annotation) to support the external type checkers to recognize any errors. This concept is a fair method for the developers and programmers to hint at the type of the object(s) being utilized while the compilation period itself ensuring that the type checkers are working correctly.

The Type Hinting also makes the Python Code pretty much robust and readable to other users.

Note: This concept does not perform the actual type checking at the compilation period. Moreover, there will be no compilation error if the original object returned was not of a similar type as hinted. Thus, we utilize the external type checkers, like mypy, in order to recognize any type errors.

Understanding mypy

In order to use the typing module effectively, it becomes necessary to utilize an external type checker or linter to check for the static type matching. The mypy is one of the most widely used type checkers, and it is recommended to install before moving ahead.

The mypy is the static type checker that can be installed using the following syntax in the command shell or terminal:

$ pip install mypy

Once the installation is complete, we can verify it by running mypy to any Python program file in order to check whether the types match. This procedure is somewhat similar to 'compiling' Python code. This can be done by typing mypy followed with the python file name. The syntax can be seen below:

$ mypy program_name.py

Once the errors debugged, we can execute the program usually using the command shown below:

$ Python program_name.py

Now, let's see some of the Pros and Cons before understanding the typing module's basic features.

Understanding the Pros and Cons of Type Hints

Some advantages of Type Hints are as follows:

1. Type Hints supports the code documentation. Usually, if we need to document the common types of the arguments in functions, we would utilize the docstrings; however, since there is no such standard for docstrings (despite PEP 257, we cannot easily use them automatically checking).
2. Type hints also help in improving the Integrated Development Environments (IDEs) as well as linters. It becomes pretty more effortless for statically reasoning about the code using them. This, in turn, enables IDEs to offer better code completion and similar properties.
3. Type hints also allow the user to construct and sustain a cleaner architecture. The type hints writing acts enable the user to think about the types in the program. Despite the fact that Python's dynamic nature is among its significant assets, being conscious about duck typing, multiple return types, or overloaded methods is a good thing.

Some Disadvantages of static type checking are as follows:

1. Type hints consumer developer time and effort for addition. Even though it probably cuts the debugging time, we can find ourselves spending more time entering code.
2. Type hints perform better in modern Pythons as we know that Annotations were introduced in Python version 3.0, and we can also use the type comments in Python version 2.7. Moreover, a user will have a much better experience performing type checks after improvements like the postponed evaluation of type hints and variable annotations in Python version 3.6 or even version 3.7.
3. Type hints also introduce a minor penalty in start-up time. This can be observed especially in short scripts where, while using the typing module, the import time may be noteworthy.

Some of us might be thinking about whether we should use static type checking in the code or not. Well, it is not an all-or-nothing question. Fortunately, Python promotes the concept of gradual typing. The gradual typing implies that we can introduce types into the code gradually. The static type checker ignores the code without type hints. Hence, we can begin inserting the types to critical components and remain as long as it adds value to us.

Moving ahead, we will notice that adding types will not have any effect on the working program or the program's users. Type checking is considered as the way to make the lives of developers better and much convenient.

Some of the thumb rules on whether to insert types to the project are as follows:

1. If the user is just a beginner in Python, he or she can wait with the type hints until grabbing some more experience.
2. Type hints provide nominal value in short throw-away scripts.
3. Type hints, specifically ones published on PyPI, adds so much value to the libraries being used by others. Other codes utilizing the libraries require these type hints to be appropriately type-checked.
4. Type hints play a significant role in Bigger Projects by helping the users understand the types flow through the code and in projects where we cooperate with others.

In an excellent article by Bernát Gábor, he recommends using the type hints whenever the unit tests are worth writing. Indeed, the type hints have a similar role to tests in the codes and support developers in writing better codes.

Fortunately, we now have an idea on the working of type checking in Python and if we should employ it in the projects or not.

Let's go through a more complex type system of Python that includes the working of static type checkers (explicitly focusing on Mypy), type check code utilizing libraries without type hints, and use of annotations at runtime.

Understanding Annotations

Annotations have initially been introduced in Python version 3.0, without any particular purpose. Annotations were the method associating the arbitrary expressions to function arguments and return the values.

As the years passed, PEP 484 was defined based on Jukka Lehtosalo's work on his Ph.D. project called Mypy, telling how to insert type hints in the python code. The primary method in order to add type hints is utilizing Annotations. The type checking is becoming much more common, implying that annotations should mainly be reserved for type hints.

Now, let's understand the working of annotation in the context of type hints.

Function Annotations

We can simply annotate arguments as well as the return value for functions. This can be done in the following way:

def function(arg: argtype, opt_arg: argtype = default) -> returntype:

    ...

For arguments, the syntax is an argument: annotation, whereas the annotation for the return type is -> annotation.

Note: The Annotation should be a valid Expression in Python.

Let us consider the following example, demonstration a simple addition of annotations to a function calculating the area of a circle:

 import math
 def area(rad: float) -> float:
     return math.pi * rad * rad
 print(area(2.45)) 

Output:

18.857409903172737

In the above example, we have imported the math module and defined a simple function to calculate the circle area and print the area for radius: 2.45, respectively. Now, let’s try inspecting the annotations. The annotations are stored in a special attribute called __annotations__ on the function.

Example:

 import math
 def area(rad: float) -> float:
     return math.pi * rad * rad
 print(area.__annotations__) 

Output:

{'rad': <class 'float'>, 'return': <class 'float'>}

Occasionally, some of us might be confused by the role of Mypy interpreting the type hints. In such cases, reveal_type() and reveal_locals() are two special expression for Mypy. We can include these expressions in the code before executing Mypy, and Mypy will obediently report the inferred types.

Let us consider the example shown below demonstrating the working of Mypy.

Example:

 # type_hints.py
 import math
 reveal_type(math.pi)
 rad = 3
 area = math.pi * rad * rad
 reveal_locals() 

Output:

 $ mypy type_hints.py 
 type_hints.py:4: note: Revealed type is 'builtins.float'
 type_hints.py:8: note: Revealed local types are:
 type_hints.py:8: note:     area: builtins.float
 type_hints.py:8: note:     rad: builtins.int 

In the above example, we have imported the math module and used the reveal_type() expression for math.pi. We have then defined the radius, rad, and area of the circle. At last, we have used the reveal_locals() expression. As a result, when we saved the file and executed the program using Mypy, Mypy has accurately inferred the built-in math.pi types as well as the local variables like rad and area even without any annotations.

Note: The reveal expressions are considered the user-friendly tool only to add types and debugging the type hints. If we try running the type_hints.py file as a Python script, it will get crashed with a NameError as the reveal_type() is not a function of the Python interpreter.

Variable Annotations

As we can observe in the definition of area() in the previous section, it is possible to annotate the arguments and the return value only. We cannot insert any annotations within the body of the function. Usually, it is enough.

However, type checker sometimes requires support to figure out the variable types also. Variable Annotations were defined in PEP 526 and introduced in Python version 3.6. The syntax for Variable Annotations is similar to the annotations of Function Arguments.

The following syntax demonstrates the same:

 pi: float = 3.142
 def area(rad: float) -> float:
     return pi * rad * rad 

We have annotated the variable pi with the type hint, float.

Variable Annotations are reserved in the module level __annotations__ dictionary:

Let us consider the following example:

Example:

 pi: float = 3.142
 def area(rad: float) -> float:
     return pi * rad * rad
 print(area(2))
 print(__annotations__) 

Output:

 12.568
 {'pi': <class 'float'>} 

In the above program, we have defined a float type variable as pi with a value of 3.142. We have then defined a function named area to calculate the size of the circle. We have also printed the area of the circle for radius = 2 and returned the variable annotations stored in the module level __annotations__ dictionary. As a result, the program returned the area and type.

We are allowed for the variable annotation without providing it a value. This inserts the annotation to the __annotations__ dictionary, whereas the variable remains undefined. The following example demonstrates the same:

Example:

 nthing: str
 print(nthing) 

Output:

 Traceback (most recent call last):
   File "D:\Python\type_hints.py", line 3, in <module>
     print(nthing)
 NameError: name 'nthing' is not defined 

In the above example, we have annotated a variable, nthing as str. But it returns a NameError as the variable ‘nthing’ is not defined.

However, if we try using the __annotations__ dictionary, it will return the type of the variable as illustrated below:

 nthing: str
 print(__annotations__) 

Output:

{'nthing': <class 'str'>}

Type Comments

Since the annotations were introduced in Python version 3 and have not been backported to Python version 2, this implies that we cannot use the annotations while writing a line of code supporting legacy Python.

In such cases, we can utilize the Type Comments. The Type Comments are specifically formatted comments utilized to insert type hints that are compatible with older code. In order to insert add type comments to a function, let us consider the following example:

Example:

 import math
 def area(rad):
     # type: (float) -> float
     return math.pi * rad * rad 

In the above example, we have created a simple function to print the area of a circle. However, we have added a comment saying type: (float) -> float. This comment is a type comment, and thus, we can use such type comments in any Python version.

Since the type checker handles these type comments directly, these types are not available in the __annotations__ dictionary.

 import math
 def area(rad):
     # type: (float) -> float
     return math.pi * rad * rad
 print(__annotations__) 

Output:

{}

In the above code, we have tried printing the annotations of the variable, and as a result, it returns an empty dictionary.

A type comment always starts with the literal “type:” and be on the lines where the function is defined. Moreover, in order to annotate a function with more than one argument, we can write each type separated by a comma.

Type Aliases

The typing module offers the Type Aliases, which is defined by a type assigned to the alias.

Let us consider the following example:

Example:

 from typing import List
 # side is a list of float values
 Side = List[float]
 def perimeter(side: Side) -> Side:
     return sum(i for i in side)
 quad = perimeter(side = [2.0, 4.0, 6.0, 8.0])
 print("Perimeter:", quad) 

Output:

Perimeter: 20.0

In the above snippet of code, we have imported the List from the typing module. We have then defined a variable side as an alias, which stands for a list of floating-point values. We have then defined a function named perimeter to print the sum of sides where we used the type hint at the alias.

Let us consider another example, which checks for every key-value pair in a dictionary and checks if they match the student_ID: student_name format.

Example:

 from typing import Dict
 # side is a list of float values
 studentDict = Dict[str, str]
 def validation(student: studentDict) -> bool:
     for student_ID, student_Name in student.items():
         if (not isinstance(student_ID, str)) or (not isinstance(student_Name, str)):
             return False
     return True
 print(validation({'10232': 'Michael Bing'}))
 print(validation({'12232': 'David Jones', 12345: 'Jenny Morgan'})) 

Output from mypy:

 mypy type_hints.py
 type_hints.py:13: error: Dict entry 1 has incompatible type "int": "str"; expected "str": "str"
 Found 1 error in 1 file (checked 1 source file) 

In the above snippet of code, we have created a simple program to return the Boolean value for every key-value pair of the dictionary. As a result, mypy returns the static compile-time error since the student_ID on our second dictionary is an integer (12345). Thus, aliases are another method of enforcing correct type checking from mypy.