Introduction to Typing Extensions

The typing-extensions Python library is a treasure trove for developers working with type annotations. It extends Python’s built-in typing module, providing forward-compatible and experimental typing features that aren’t yet available in the main typing module. These additions enable enhanced readability, error-checking, and code quality in Python applications.

Why Use Typing Extensions?

The standard typing module has been a core tool for improving type safety and static analysis in Python. However, Python’s typing system evolves over time, and not all features make it into the standard library immediately. Fortunately, typing-extensions acts as a bridge, offering access to new, experimental, or forward-ported type features regardless of your Python version.

Key APIs in Typing Extensions

1. Literal

Enables usage of specific literal values as types:

  from typing_extensions import Literal

  def process_status(status: Literal["success", "failure", "pending"]) -> str:
      if status == "success":
          return "Operation was successful!"
      elif status == "failure":
          return "The operation failed."
      else:
          return "Operation is still pending."

  print(process_status("success"))

2. TypedDict

Defines dictionary-like objects with specific constraints on their structure:

  from typing_extensions import TypedDict

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

  user: User = {"name": "Alice", "age": 30, "email": "alice@example.com"}
  print(user["name"])

3. Protocol

Allows defining behavioral contracts for objects:

  from typing_extensions import Protocol

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

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

  def perform_greeting(greeter: Greeter) -> None:
      print(greeter.greet())

  perform_greeting(FriendlyGreeter())

4. Annotated

Attaches metadata to types:

  from typing_extensions import Annotated

  def format_number(number: Annotated[int, "Must be a positive integer"]) -> str:
      return f"{number:,}"

  print(format_number(1000))

5. Self

Defines methods that return the same instance type:

  from typing_extensions import Self

  class FluentString:
      def __init__(self, text: str):
          self._text = text

      def append(self, suffix: str) -> Self:
          self._text += suffix
          return self

      def __str__(self) -> str:
          return self._text

  string = FluentString("Hello").append(" World").append("!")
  print(string)

6. Final

Prevents subclassing of classes or overriding of methods:

  from typing_extensions import Final

  MAX_SCORE: Final = 100

  MAX_SCORE = 200  # Raises error in type checkers

7. @runtime_checkable

Makes a protocol usable with isinstance() and issubclass():

  from typing_extensions import Protocol, runtime_checkable

  @runtime_checkable
  class Movable(Protocol):
      def move(self) -> None:
          ...

  class Car:
      def move(self) -> None:
          print("Car is moving!")

  car = Car()
  print(isinstance(car, Movable))  # Outputs: True

Real-World Example: Task Management App

Here’s a simple example of a task management app that utilizes several features from typing-extensions:

  from typing_extensions import TypedDict, Literal, Annotated, Protocol


  class Task(TypedDict):
      title: str
      status: Literal["todo", "in-progress", "done"]
      priority: Annotated[int, "Priority must be between 1 (high) and 10 (low)"]

  
  class Renderable(Protocol):
      def render(self) -> str:
          ...


  class TaskCard:
      def __init__(self, task: Task):
          self.task = task

      def render(self) -> str:
          return f"[{self.task['status'].upper()}] {self.task['title']} (Priority: {self.task['priority']})"


  # Example data
  tasks = [
      {"title": "Write Blog Post", "status": "in-progress", "priority": 2},
      {"title": "Fix Bugs", "status": "todo", "priority": 5},
      {"title": "Release Update", "status": "done", "priority": 1},
  ]

  for task_data in tasks:
      task_card = TaskCard(task_data)
      print(task_card.render())

By leveraging TypedDict, Literal, and Protocol, this task management app achieves highly structured and type-safe code, ensuring clarity and maintainability.

Conclusion

With typing-extensions in your toolkit, you can take advantage of the latest Python typing features, even if they aren’t officially part of the standard typing module yet. The library is a must-have for writing clean, maintainable, and type-safe Python code, especially for large-scale applications.