Introduction to typing-extensions

typing-extensions is a powerful Python library that extends the capabilities of the standard typing module. It acts as a bridge to provide features from future Python versions to older versions, ensuring you can utilize modern typing features even if you’re working with an older interpreter. This library is essential for Python developers who aim to write robust, maintainable, and highly-typed code. Let’s dive deep into this toolkit with plenty of examples and usage scenarios.

Why Use typing-extensions?

Python’s typing module has transformed how developers write type-safe code. However, not all versions of Python support the latest type features. typing-extensions acts as a backport, bringing modern typing constructs to earlier Python versions. Some of the most useful APIs include Literal, TypedDict, Final, Protocol, and more.

Key APIs from typing-extensions

1. Literal

The Literal type allows you to specify that a variable or function argument must be one of a specific set of values.

  from typing_extensions import Literal

  def get_status_code(status: Literal["success", "error"]) -> int:
      if status == "success":
          return 200
      elif status == "error":
          return 500
      else:
          raise ValueError("Invalid status")

  print(get_status_code("success"))  # Output: 200

2. TypedDict

TypedDict allows you to define dictionary-like structures with type checking for their keys and values.

  from typing_extensions import TypedDict

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

  my_book: Book = {
      "title": "1984",
      "author": "George Orwell",
      "pages": 328
  }

  print(my_book["title"])  # Output: 1984

3. Final

Final is used to mark a variable as immutable (constant) after its initial definition.

  from typing_extensions import Final

  API_URL: Final = "https://api.example.com"
  # API_URL = "https://new-api.example.com"  # This would raise a type error

4. Protocol

Protocol allows for structural subtyping. This is incredibly useful for adhering to a “duck typing” approach while still getting type-checking benefits.

  from typing_extensions import Protocol

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

  class FriendlyGreeter:
      def greet(self, name: str) -> str:
          return f"Hello, {name}!"

  def introduce(greeter: Greeter, name: str) -> None:
      print(greeter.greet(name))

  greeter = FriendlyGreeter()
  introduce(greeter, "Alice")  # Output: Hello, Alice!

5. @override

Use @override to ensure that a method in a subclass matches a method in the superclass.

  from typing_extensions import override

  class Base:
      def process_data(self, data: str) -> str:
          return data.upper()

  class Child(Base):
      @override
      def process_data(self, data: str) -> str:
          return f"Processed: {data}"

  obj = Child()
  print(obj.process_data("test"))  # Output: Processed: test

6. Required and NotRequired

These extensions allow better control over optional and mandatory keys in TypedDict.

  from typing_extensions import TypedDict, Required, NotRequired

  class User(TypedDict, total=False):
      username: Required[str]
      email: NotRequired[str]

  user: User = {"username": "johndoe"}
  print(user)  # Output: {'username': 'johndoe'}

Building an Application with typing-extensions

Here’s an example of a simple library management application using several typing-extensions features:

  from typing_extensions import TypedDict, Protocol, Literal, Final

  LIBRARY_NAME: Final = "MyLibrary"

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

  class LibraryProtocol(Protocol):
      def add_book(self, book: Book) -> None:
          ...

      def borrow_book(self, title: str) -> Literal["borrowed", "unavailable"]:
          ...

  class Library(LibraryProtocol):
      def __init__(self):
          self.books = []

      def add_book(self, book: Book) -> None:
          self.books.append(book)

      def borrow_book(self, title: str) -> Literal["borrowed", "unavailable"]:
          for book in self.books:
              if book["title"] == title and book["available"]:
                  book["available"] = False
                  return "borrowed"
          return "unavailable"

  library = Library()
  library.add_book({"title": "1984", "author": "George Orwell", "available": True})
  print(library.borrow_book("1984"))  # Output: borrowed
  print(library.borrow_book("1984"))  # Output: unavailable

Conclusion

The typing-extensions library is an indispensable tool for developers aiming to harness the power of modern Python typing features across different versions of the language. With its rich set of utilities ranging from Literal to Protocol, it not only ensures type safety but also enhances code readability and maintainability. Start integrating typing-extensions into your Python projects and experience the benefits of robust type checking!