An Introduction to Typing-Extensions in Python

The typing-extensions package is a versatile Python library that serves as a supplemental module to the built-in typing library. It allows developers to experiment with and adopt new type hinting and typing-related features before they’re officially added to the Python standard library. This is especially useful for projects that need forward compatibility with type-checkers like mypy or for developers working across different Python versions.

In this article, we will explore some of the most useful APIs offered by typing-extensions. Additionally, we’ll incorporate these APIs into a sample Python app. By the end, you’ll not only understand the practical utility of these features but also be equipped to implement them in your projects effectively.

Key Features and APIs of Typing-Extensions

Here’s a comprehensive list of APIs provided by typing-extensions, along with code examples for each:

1. TypedDict

TypedDict allows you to specify the structure of dictionaries with key-value pairs where both keys and values have predefined types. This is particularly useful for working with JSON-like data structures.

  from typing_extensions import TypedDict

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

  user: User = {"id": 1, "name": "John Doe", "email": "johndoe@example.com"}

2. Literal

Allows specifying a specific set of constant values for a type.

  from typing_extensions import Literal

  def get_status(status: Literal["success", "error"]) -> None:
      print(f"Status: {status}")

  get_status("success")  # Valid
  # get_status("unknown")  # Error

3. Final

Marks a variable or method as final, meaning it cannot be reassigned or overridden.

  from typing_extensions import Final

  API_URL: Final = "https://api.example.com"

  # API_URL = "https://newapi.example.com"  # Error

4. Annotated

Adds metadata to type hints, useful for validating or describing types.

  from typing_extensions import Annotated

  def process_text(text: Annotated[str, "Must be a non-empty string"]) -> str:
      assert text, "Text cannot be empty"
      return text.upper()

  print(process_text("hello"))  # Outputs: HELLO

5. Self

Helps define methods that return an instance of the same class when hinting.

  from typing_extensions import Self

  class Builder:
      def set_name(self, name: str) -> Self:
          self.name = name
          return self

      def set_age(self, age: int) -> Self:
          self.age = age
          return self

  builder = Builder().set_name("John").set_age(30)

6. Protocol

Defines an interface that any implementing class must adhere to.

  from typing_extensions import Protocol

  class Flyer(Protocol):
      def fly(self) -> str:
          ...

  class Bird:
      def fly(self) -> str:
          return "I am flying"

  bird: Flyer = Bird()
  print(bird.fly())  # Outputs: I am flying

7. Never

Represents a function that never returns, like a function that always raises exceptions.

  from typing_extensions import Never

  def raise_error(message: str) -> Never:
      raise ValueError(message)

Building a Practical Application Using Typing-Extensions

To understand the real-world utility of typing-extensions, let’s build a small app using the APIs discussed above.

App: User Registration System

  from typing_extensions import TypedDict, Literal, Annotated, Final, Protocol

  # Define constants
  STATUS: Final[Literal["active", "inactive", "banned"]] = "active"

  # Define a dictionary structure using TypedDict
  class User(TypedDict):
      id: int
      name: str
      email: str
      status: Literal["active", "inactive", "banned"]

  # Define a protocol for sending notifications
  class Notifier(Protocol):
      def send_notification(self, user: User, message: str) -> None:
          ...

  class EmailNotifier:
      def send_notification(self, user: User, message: str) -> None:
          print(f"Sending email to {user['email']}: {message}")

  class UserManager:
      def __init__(self, notifier: Notifier):
          self.notifier = notifier

      def register_user(self, id: int, name: str, email: str) -> User:
          user: User = {
              "id": id,
              "name": name,
              "email": email,
              "status": STATUS
          }
          self.notifier.send_notification(user, "Welcome!")
          return user

  # Usage example
  notifier = EmailNotifier()
  user_manager = UserManager(notifier)
  user = user_manager.register_user(1, "Alice", "alice@example.com")
  print(user)

Conclusion

The typing-extensions library is a must-have tool for Python developers who want to leverage advanced type-checking features and write more robust, understandable, and maintainable code. Whether you’re working on a simple script or a complex application, the additional flexibility and clarity provided by typing-extensions can make your code easier to read and debug.