Welcome to the Comprehensive Guide on typing-extensions

The typing-extensions library is an essential package in the Python ecosystem, offering access to new typing features even when using older versions of Python. It acts as a bridge to provide backward compatibility and allows developers to leverage typing advancements without upgrading Python versions.

Why Use typing-extensions?

As Python evolves, new typing features are frequently added to support type safety and clarity in code. However, upgrading Python is not always an option in certain environments. This is where typing-extensions comes in: it backports these features to older versions of Python, enabling developers to use modern tools like TypedDict, Literal, and Protocol.

Key APIs in typing-extensions with Examples

Using TypedDict

The TypedDict class allows you to define a dictionary with a fixed set of keys, each with a specific type.

  from typing_extensions import TypedDict

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

  user_data: User = {"id": 1, "name": "Alice", "email": "alice@example.com"}

Using Literal

The Literal type restricts a value to a specific set of allowed values.

  from typing_extensions import Literal

  def get_status_code(status: Literal["SUCCESS", "FAILURE", "PENDING"]) -> int:
      if status == "SUCCESS":
          return 200
      elif status == "FAILURE":
          return 500
      else:  # PENDING
          return 102

Using Protocol

The Protocol type helps define structural subtyping. This is useful for ensuring that objects conform to specific method signatures without inheriting from a common interface.

  from typing_extensions import Protocol

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

  class FriendlyGreeter:
      def greet(self) -> str:
          return "Hello, friend!"

  def show_greeting(greeter: Greeter):
      print(greeter.greet())

  greeter_instance = FriendlyGreeter()
  show_greeting(greeter_instance)

Using Concatenate and ParamSpec

These features allow you to work with variadic arguments by modifying callable signatures programmatically.

  from typing import Callable
  from typing_extensions import Concatenate, ParamSpec

  P = ParamSpec('P')

  def add_authentication(func: Callable[Concatenate[str, P], str]) -> Callable[P, str]:
      def wrapper(*args: P.args, **kwargs: P.kwargs) -> str:
          user_id = "user_123"
          return func(user_id, *args, **kwargs)
      return wrapper

  @add_authentication
  def get_data(user_id: str, resource: str) -> str:
      return f"Data for {user_id} from {resource}"

  print(get_data("resource123"))

A Real-world Application Example

Combining different features of typing-extensions, let’s build an application to manage tasks:

  from typing_extensions import TypedDict, Literal, Protocol

  class Task(TypedDict):
      id: int
      title: str
      status: Literal["TODO", "IN_PROGRESS", "DONE"]

  class TaskManager(Protocol):
      def add_task(self, task: Task) -> None:
          ...
      def get_task(self, task_id: int) -> Task:
          ...
      def update_task_status(self, task_id: int, status: Literal["TODO", "IN_PROGRESS", "DONE"]) -> None:
          ...

  class SimpleTaskManager:
      def __init__(self):
          self.tasks = {}

      def add_task(self, task: Task) -> None:
          self.tasks[task["id"]] = task

      def get_task(self, task_id: int) -> Task:
          return self.tasks[task_id]

      def update_task_status(self, task_id: int, status: Literal["TODO", "IN_PROGRESS", "DONE"]) -> None:
          self.tasks[task_id]["status"] = status

  task_manager = SimpleTaskManager()
  task_manager.add_task({"id": 1, "title": "Learn typing-extensions", "status": "TODO"})
  task_manager.update_task_status(1, "IN_PROGRESS")
  print(task_manager.get_task(1))

Conclusion

The typing-extensions library is a powerful tool for enhancing code clarity, maintainability, and type safety, even on older Python versions. By leveraging its features, developers can write robust and forward-compatible applications easily.