Introduction to typing-extensions
The Python ecosystem has witnessed tremendous growth over the years, and with the increasing size of codebases, developers are leaning more towards tools that offer better type safety. While Python introduced type hints as part of its base functionality in PEP 484, newer and more advanced typing features are often released as part of the typing-extensions module before being integrated into the standard library. This ensures that developers using older Python versions can still leverage modern type hinting capabilities. In this blog post, we provide an in-depth guide to typing-extensions, along with dozens of useful code snippets and examples for various use cases.
Why Use typing-extensions?
typing-extensions is a backport of features introduced in the typing module for Python 3.x. It provides developers access to cutting-edge typing features, regardless of the Python version they are working with. This ensures code compatibility with legacy versions while maintaining the benefits of type correctness and code intelligence.
Features and Examples:
1. Literal
Sometimes, you want to limit the possible values of a variable to a predefined set of values. The Literal type allows for this:
from typing_extensions import Literal
def set_mode(mode: Literal["auto", "manual", "off"]) -> None:
print(f"Mode set to {mode}")
set_mode("auto") # Valid
set_mode("manual") # Valid
set_mode("unknown") # Error
2. TypedDict
TypedDict allows defining dictionary-like objects with fixed keys and types for those keys.
from typing_extensions import TypedDict
class User(TypedDict):
name: str
age: int
is_active: bool
user: User = {"name": "Alice", "age": 30, "is_active": True}
3. Protocol
Protocols are a way to define structural subtyping, similar to interfaces in other programming languages.
from typing_extensions import Protocol
class Greeter(Protocol):
def greet(self) -> str:
...
class Person:
def greet(self) -> str:
return "Hello, world!"
def say_hello(entity: Greeter) -> None:
print(entity.greet())
say_hello(Person())
4. Final
Final is used to indicate that a class, method, or variable should not be overridden or reassigned.
from typing_extensions import Final PI: Final = 3.14159 PI = 3 # Error: cannot reassign a Final variable
5. Annotated
The Annotated type allows attaching metadata to type hints.
from typing import Annotated
from typing_extensions import Annotated
def process_data(data: Annotated[int, "Must be non-negative"]) -> None:
print(data)
6. Overload
Overload enables function overloading where multiple type signatures are specified for the same function.
from typing_extensions import overload
@overload
def load_data(data: str) -> str:
...
@overload
def load_data(data: int) -> int:
...
def load_data(data):
if isinstance(data, str):
return data.upper()
elif isinstance(data, int):
return data * 2
7. Self
The Self type lets you annotate methods that return an instance of their class.
from typing_extensions import Self
class Builder:
def set_property(self, key: str, value: str) -> Self:
print(f"Setting {key} to {value}")
return self
Example Application
Let’s build a simple application using the above features:
from typing_extensions import Literal, Protocol, Final, TypedDict, Self
# Define a configuration TypedDict
class Config(TypedDict):
environment: Literal["dev", "staging", "prod"]
debug: bool
# Protocol for services
class Service(Protocol):
def start(self) -> None: ...
def stop(self) -> None: ...
# Example class using Protocol and Final
class DatabaseService:
name: Final = "DatabaseService"
def start(self) -> None:
print("Database Service started.")
def stop(self) -> None:
print("Database Service stopped.")
# Main application class
class App:
def __init__(self, config: Config) -> None:
self.config = config
print(f"App launched in {self.config['environment']} mode")
def add_service(self, service: Service) -> Self:
service.start()
return self
# Example configuration and usage
config: Config = {"environment": "dev", "debug": True}
app = App(config)
app.add_service(DatabaseService())
The above example shows how typing-extensions helps structure and type Python code better, resulting in more maintainable and error-proof applications.
Conclusion
The typing-extensions module is indispensable for Python developers looking to adopt modern typing features across different Python versions. It ensures code clarity, maintainability, and robustness. Leverage these tools in your projects to improve type safety and developer productivity!
