Introduction to Typing-Extensions

The typing-extensions module is an essential library for Python developers wanting to utilize forward-compatible type hints in their projects. It extends the functionality of Python’s standard typing module by offering backports of features from bleeding-edge Python versions and some experimental APIs that may later become part of Python’s typing module. This ensures you can write modern, expressive, and maintainable type hints, even when working with older versions of Python.

Core Features and APIs in Typing-Extensions

Let us explore the wide range of APIs provided by typing-extensions with practical examples:

1. Literal Type

The Literal type restricts a variable to have specific values. It improves code readability and adds strictness to type annotations.

  from typing_extensions import Literal

  def get_status(status: Literal["success", "failure", "pending"]) -> str:
      return f"Status is: {status}"

  print(get_status("success"))  # Valid
  # print(get_status("unknown"))  # Throws type-checking error

2. TypedDict

TypedDict allows defining structured types where the dictionary keys have specific names and corresponding value types.

  from typing_extensions import TypedDict

  class User(TypedDict):
      id: int
      name: str
      email: str

  user: User = {"id": 1, "name": "Alice", "email": "alice@example.com"}
  print(user)

3. Protocol

Protocol enables structural subtyping by defining the expected methods or properties of a class, regardless of class inheritance.

  from typing_extensions import Protocol

  class Greetable(Protocol):
      def greet(self) -> str:
          ...

  class Person:
      def greet(self) -> str:
          return "Hello!"

  def greet_entity(entity: Greetable) -> str:
      return entity.greet()

  person = Person()
  print(greet_entity(person))  # Outputs "Hello!"

4. Final

Final prevents reassignment of variables and subclassing of methods or classes.

  from typing_extensions import Final

  MAX_CONNECTIONS: Final[int] = 10

  # MAX_CONNECTIONS = 15  # Raises a type-checking error

5. Annotated

Annotated allows enriching type hints with additional metadata such as validation or documentation.

  from typing_extensions import Annotated

  def age_category(age: Annotated[int, "Age must be an integer between 0 and 120"]) -> str:
      if age < 18:
          return "Minor"
      elif age <= 60:
          return "Adult"
      else:
          return "Senior"

  print(age_category(25))  # Outputs "Adult"

Complete Application Example with Typing-Extensions

Here's a complete example of a simple user management system leveraging multiple features from typing-extensions.

  from typing_extensions import TypedDict, Final, Literal, Annotated, Protocol

  # Define a TypedDict for a User
  class User(TypedDict):
      id: int
      name: str
      email: str
      role: Literal["admin", "editor", "viewer"]

  # Define a Protocol for a RoleHandler
  class RoleHandler(Protocol):
      def handle_role(self, user: User) -> str:
          ...

  # Final constant for the max allowed users
  MAX_USERS: Final[int] = 100

  # Function to add a user with Annotated type hint
  def add_user(user: Annotated[User, "Must match the User schema"]) -> str:
      return f"User {user['name']} added with role {user['role']}."

  # Role Manager implementing the RoleHandler Protocol
  class RoleManager:
      def handle_role(self, user: User) -> str:
          return f"The user {user['name']} has the role {user['role']}."

  # App Logic
  if __name__ == "__main__":
      user1 = {"id": 1, "name": "Alice", "email": "alice@example.com", "role": "admin"}
      role_manager = RoleManager()

      print(add_user(user1))
      print(role_manager.handle_role(user1))

This app combines various type hints such as TypedDict, Final, Literal, Annotated, and Protocol for a clean, maintainable, and type-safe implementation.

Conclusion

The typing-extensions module is a powerful addition to Python's type hinting ecosystem, enabling developers to adopt new typing features before they become universally available or rely on them in older versions of Python. With its ability to improve code clarity, maintainability, and reliability, it's a must-have library for modern Python development.