An Introduction to Typing Extensions: Enhancing Python Typing

The typing-extensions module is a critical library for Python developers working with type annotations. It provides access to new typing features before they are officially integrated into Python’s typing module, as well as offering some backward compatibility for older versions of Python. By using typing-extensions, developers can write more expressive, readable, and maintainable code.

In this guide, we will dive into several APIs provided by typing-extensions, complete with code examples, and create a real-world app that demonstrates their usage.

Key APIs in Typing Extensions

1. Literal

The Literal type allows you to specify that a variable can only have a specific set of literal values.

  from typing_extensions import Literal

  def process_data(operation: Literal['create', 'update', 'delete']):
      if operation == 'create':
          return "Creating data..."
      elif operation == 'update':
          return "Updating data..."
      elif operation == 'delete':
          return "Deleting data..."

  print(process_data('create'))  # Valid
  # print(process_data('read'))  # Raises a type-checking error

2. TypedDict

TypedDict helps define type-checked dictionaries with specific key-value pairs.

  from typing_extensions import TypedDict

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

  def display_user(user: User):
      return f"User {user['name']} with email {user['email']}"

  user_data = {"id": 1, "name": "Alice", "email": "alice@example.com"}
  print(display_user(user_data))  # Output: User Alice with email alice@example.com

3. Protocol

Protocol is useful for structural subtyping (or “duck typing”). It allows you to define an interface and ensure that other classes adhere to it.

  from typing_extensions import Protocol

  class Drawable(Protocol):
      def draw(self) -> None:
          pass

  class Circle:
      def draw(self) -> None:
          print("Drawing a circle!")

  def render(obj: Drawable):
      obj.draw()

  circle = Circle()
  render(circle)  # Output: Drawing a circle!

4. Final

The Final type indicates that a variable or method cannot be overridden or reassigned.

  from typing_extensions import Final

  MAX_USERS: Final = 10

  # MAX_USERS = 15  # Raises a type-checking error

5. @runtime_checkable

Using @runtime_checkable with protocols makes them available for runtime type checking.

  from typing_extensions import Protocol, runtime_checkable

  @runtime_checkable
  class Walker(Protocol):
      def walk(self) -> None:
          pass

  class Dog:
      def walk(self) -> None:
          print("Walking the dog")

  my_dog = Dog()
  print(isinstance(my_dog, Walker))  # True

6. Concatenate and ParamSpec

Advanced type manipulation can be done using Concatenate and ParamSpec.

  from typing_extensions import Concatenate, ParamSpec, Callable
  P = ParamSpec('P')

  def add_logging(func: Callable[Concatenate[str, P], None]) -> Callable[P, None]:
      def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
          print(f"Logging: {args}, {kwargs}")
          return func("LOG:", *args, **kwargs)
      return wrapper

  def my_function(prefix: str, x: int, y: int) -> None:
      print(f"{prefix} {x} + {y} = {x + y}")

  logged_function = add_logging(my_function)
  logged_function(2, 3)  # Output: Logging: (2, 3), {}
                         # LOG: 2 + 3 = 5

Practical App Example Using Typing Extensions

Let’s build a basic task management app that uses TypedDict, Literal, and Protocol.

  from typing_extensions import TypedDict, Literal, Protocol

  class Task(TypedDict):
      id: int
      title: str
      status: Literal['pending', 'in-progress', 'completed']

  class TaskManager(Protocol):
      def add_task(self, task: Task) -> None:
          pass
      def list_tasks(self) -> list[Task]:
          pass

  class SimpleTaskManager:
      def __init__(self):
          self.tasks: list[Task] = []

      def add_task(self, task: Task) -> None:
          self.tasks.append(task)

      def list_tasks(self) -> list[Task]:
          return self.tasks

  manager: TaskManager = SimpleTaskManager()
  manager.add_task({"id": 1, "title": "Learn Python", "status": "pending"})
  manager.add_task({"id": 2, "title": "Study Typing", "status": "in-progress"})

  for task in manager.list_tasks():
      print(f"Task {task['id']}: {task['title']} [{task['status']}]")

This example shows how typing-extensions can improve code safety and maintainability in a real-world application.

Conclusion

The typing-extensions module is a fantastic tool to enhance Python’s type system. By using its features, you can write clean, robust, and forward-compatible code. Whether you’re building small scripts or enterprise-grade applications, mastering these APIs will surely level up your Python coding skills.