Understanding Typing Extensions in Python

The typing-extensions module is a powerful library designed to backport new features introduced in the Python typing module. It allows developers to use the latest type hints and utilities regardless of the Python version they’re using. This article explores the most useful APIs from typing-extensions, complete with examples to help you get started. These tools can make your code more robust, readable, and maintainable, especially in large and complex projects.

Key APIs in Typing Extensions with Examples

1. Literal

The Literal type allows you to define strict values that a variable or parameter can accept.

  from typing_extensions import Literal

  def greet_person(greet_type: Literal["formal", "casual"]) -> str:
      if greet_type == "formal":
          return "Hello, how do you do?"
      elif greet_type == "casual":
          return "Hi, what's up?"
  
  print(greet_person("formal"))  # "Hello, how do you do?"
  

2. TypedDict

TypedDict allows you to create dictionaries with strict key-value types.

  from typing_extensions import TypedDict

  class Book(TypedDict):
      title: str
      author: str
      pages: int

  my_book: Book = {
      "title": "The Great Gatsby",
      "author": "F. Scott Fitzgerald",
      "pages": 218,
  }
  

3. Annotated

Use Annotated to attach metadata to types, making them more informative for tooling and frameworks.

  from typing_extensions import Annotated

  def process_data(data: Annotated[int, "Must be a positive integer"]) -> int:
      # Metadata is purely for descriptive tooling, not enforced
      return data * 2

  print(process_data(5))  # 10
  

4. Final

Final is used to declare variables or classes as non-overridable.

  from typing_extensions import Final

  MAX_CONNECTIONS: Final = 100

  print(MAX_CONNECTIONS)  # 100
  

5. Protocol

The Protocol type describes structural subtyping, useful for interface-like definitions.

  from typing_extensions import Protocol

  class Writable(Protocol):
      def write(self, content: str) -> None:
          pass

  class FileWriter:
      def write(self, content: str) -> None:
          print(f"Writing to file: {content}")

  def save_data(writer: Writable, data: str) -> None:
      writer.write(data)

  save_data(FileWriter(), "Hello, World!")
  

6. Self

The Self type allows you to annotate return types for methods in class definitions.

  from typing_extensions import Self

  class ShoppingCart:
      def add_item(self, item: str) -> Self:
          print(f"Adding {item} to cart")
          return self

  cart = ShoppingCart().add_item("Apples").add_item("Oranges")
  

A Practical App Example Using Typing Extensions

Let’s build a simple library management application that utilizes multiple APIs from typing-extensions.

  from typing_extensions import TypedDict, Protocol, Literal

  class Book(TypedDict):
      title: str
      author: str
      available: bool

  class Inventory(Protocol):
      def add_book(self, book: Book) -> None:
          pass

      def find_book(self, title: str) -> Literal["Found", "Not Found"]:
          pass

  class LibraryInventory:
      def __init__(self) -> None:
          self.books = []

      def add_book(self, book: Book) -> None:
          self.books.append(book)
          print(f"Added book: {book['title']}")

      def find_book(self, title: str) -> Literal["Found", "Not Found"]:
          for book in self.books:
              if book["title"] == title:
                  return "Found"
          return "Not Found"

  # App usage
  library = LibraryInventory()
  library.add_book({"title": "1984", "author": "George Orwell", "available": True})
  result = library.find_book("1984")
  print(result)
  

Why Use Typing Extensions?

typing-extensions allows Python developers to adopt modern typing features without waiting for the next Python release. This makes it an invaluable tool for type-safety, better debugging, and enhanced code quality in Python projects.

Conclusion

With tools like Literal, TypedDict, Protocol, and others, typing-extensions opens a world of possibilities for Python typing customization. Exploring these features will help you write cleaner, more maintainable code. Start including typing-extensions in your next project and notice the difference!