PEP 484

Overview Python Type Hints represent more than just a way to catch bugs. While introduced in PEP 484 to provide optional static-like typing, their true value lies in software design. They force developers to define the interfaces of their functions clearly, which naturally leads to more flexible and reusable code. By moving beyond basic primitives, you can architect systems that adhere to the Open-Closed Principle. Prerequisites To follow this guide, you should have a baseline understanding of Python 3.5+ syntax, particularly functions and classes. Familiarity with basic data structures like lists and dictionaries is necessary. Some experience with VS Code or similar IDEs with static analysis tools is helpful for seeing type errors in real-time. Key Libraries & Tools - `typing`: The standard library module for type hint support. - `collections.abc`: Contains abstract base classes like `Iterable` for generic input types. - `Protocols`: Used for structural subtyping (duck typing via hints). Code Walkthrough: Generic Inputs When defining function arguments, use the most generic type possible. Using `list[float]` restricts your function unnecessarily. Instead, use `Iterable[float]` to allow lists, tuples, or even generators. ```python from collections.abc import Iterable def calculate_discount(items: Iterable[float], discount: float) -> list[float]: return [item * (1 - discount) for item in items] ``` In this snippet, changing the input to `Iterable` allows the function to handle a wider range of data structures without modifying the logic. This makes the input "contravariant"—it accepts a wide range of types. Code Walkthrough: Specific Outputs While inputs should be generic, outputs must be specific. This ensures the caller knows exactly what methods are available on the returned object. Returning a generic `DatabaseConnection` protocol hides specific features like `start_transaction` if that method only exists on a `PostgresConnection` class. ```python class PostgresConnection: def execute(self, query: str): ... def start_transaction(self): ... def connect_db() -> PostgresConnection: return PostgresConnection() ``` By specifying `PostgresConnection` as the return type, the IDE provides full autocomplete for all specialized methods, making the output "covariant." Syntax Notes Modern Python (3.9+) allows using lowercase `list` and `dict` for generics. Python 3.12 introduced a simplified generic syntax for classes and functions, reducing the need for explicit `TypeVar` declarations in many scenarios. Practical Examples - **Reporting Systems:** Use `Protocols` to define an `Exporter` interface. This allows adding `CSVExporter` or `JSONExporter` classes without changing the core reporting logic. - **Data Processing:** Accept an `Iterable` for data streams to process large datasets via generators without loading everything into memory. Tips & Gotchas Python ignores type hints at runtime. If you pass a string to a function expecting a float, Python will not stop you unless you use a static type checker like MyPy or the built-in analyzer in your IDE. Always remember: generic for input, specific for output.