Type hints and collections

Introduction

A traditional way to use the type hints tool in Python is to specify the type of a variable when it's created as a typical data type (like int, bool, float, and so on). However, this might be insufficient, especially when we want to define a variable as a collection (such as a list, tuple, dictionary) rather than a single traditional data type. So, learning how to use type hints for collections and self-defined data types and classes is essential.

To make type hints easier to use, we often refer to the typing module. This module is part of Python's standard library and helps us work with type hints and annotations. It provides different classes, functions, and types that we can use to specify the types in our code.

This topic will discuss how to use type hints for collections and self-defined data types. We will also show you how to use the typing module to help with type hints.

Typing module

Typing is a module in Python's standard library that supports type hints and annotations. Type hints allow you to specify the expected types of variables, function arguments, and return values in your code. This enhances code readability and can be used by tools for static type checking, code analysis, and auto-completion.

The typing module provides various classes, functions, and types that you can use to annotate your code. Some of the commonly used constructs from the typing module include:

1. Basic types:

• int, str, float, bool: basic built-in types in Python.

• List, Tuple, Set, Dict: generic types representing lists, tuples, sets, and dictionaries, respectively.

2. Type aliases:

• TypeAlias = ...: you can create your type aliases for better code readability.

3. Union types:

• Union[type1, type2, ...]: represents a value that can be of any of the specified types.

4. Optional types:

• Optional[type]: equivalent to Union[type, None], indicating that a value can be of the specified type or None.

5. Callable types:

• Callable[..., returnType]: represents a callable with specified arguments and return type.

6. Any type:

• Any: represents any type, indicating that type checking is not required for that variable.

7. Generics:

• TypeVar: defines generic types that can vary in actual type but maintain some typical relationship.

8. Literal types:

• Literal[value1, value2, ...]: represents a value that can only be one of the specified literals.

9. Classes for type hinting:

• NewType: creates distinct type hints for better type safety.

• NamedTuple: allows creating named tuples with annotated field types.

10. Type narrowing:

• TypeGuard: lets you annotate the return type of a user-defined type guard function, aiding type narrowing, which helps static type checkers determine more precise types within a program's code flow.

Here's a simple example of how the typing module can be used for type hints:

from typing import List, Union

def process_data(data: Union[str, List[int]]) -> str:
    if isinstance(data, str):
        return f"Processed string: {data}"
    elif isinstance(data, list):
        return f"Processed list: {sum(data)}"
    else:
        return "Unknown data"

result1 = process_data("Hello")
result2 = process_data([1, 2, 3])

print(result1)  # Output: Processed string: Hello
print(result2)  # Output: Processed list: 6

In this example, the Union type is used to indicate that the data parameter can be either a string or a list of integers. Depending on the type used, the function will return different strings: for string input, it would return Processed string: and the string itself; for a list of ints, it would be Processed list: and the sum of elements of the list; and for any other data types, the function would return Unknown data. Note that if a variable of a wrong type is passed to the function, the program will still be executed correctly (and Unknown data will be printed). However, the IDE would print a warning informing that an unexpected type is used.

Type hints for collections

In Python, type hints provide a way to indicate the expected data types of variables, function parameters, and return values. When working with collections such as lists, dictionaries, tuples, and sets, type hints can significantly improve code readability and help catch potential type-related errors early in development. For example, when defining a function that takes a list of integers as an argument, you can use the List type hint from the typing module to indicate this:

from typing import List

def process_numbers(numbers: List[int]) -> List[int]:
    squared_numbers = [num ** 2 for num in numbers]
    return squared_numbers

In this example, the process_numbers function takes a list of integers as its argument and returns a new list of squared integers. The List[int] type hint clarifies the expected input type, making it clear to developers and tools that the function should be called with a list containing integers.

Type hints for self-defined data types

Python also allows you to create your custom data types using classes. When working with the self-defined data types, type hints become particularly valuable to convey the intended structure of your data and methods. Let's consider a basic example of a Person class:

class Person:
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

    def introduce(self) -> str:
        return f"Hi, I'm {self.name} and I'm {self.age} years old."

def celebrate_birthday(person: Person) -> Person:
    person.age += 1
    return person

In this scenario, the Person class has two attributes name and age and the method introduce. The type hints for the __init__ constructor and the introduce method clarifies the expected input and return types. Additionally, the celebrate_birthday function takes a Person object as an argument and returns a modified Person object after incrementing the age. Type hints provide insight into the structure of the custom data type and how it can be used within functions.

Why is it important? While the typing module provides runtime support for type hints; it does not enforce function and variable type annotations, which means IDE and other third-party type checkers could use them but not affect the program execution if a variable of a wrong type is used. Please note that type hints in Python are only informational.

Conclusion

Type hints in Python programming are a great help as they clarify data types of variables, function parameters, and return values. The typing module, available in the standard library, provides various annotation tools, making the code more readable and enabling static type checking. Type hints are handy when working with collections like lists and dictionaries and defining custom data types with classes. By using type hints, developers can create more robust code, promoting better collaboration and reducing the possibility of errors.