Introduction to Typing-Extensions

Python has been a dominant force in software development, thanks to its simplicity and extensive libraries. Over recent years, the importance of adding type hints for better clarity and maintainability has risen. The typing-extensions library extends Python’s typing module, providing additional type hinting utilities that aren’t available in older versions of Python. This guide introduces you to the library’s core features and demonstrates practical applications step-by-step.

Why Typing-Extensions Matters

The typing-extensions library allows developers to use features from typing that are only available in newer Python versions, making it backward compatible with older Python releases. Below are dozens of examples to demonstrate the power of these utilities.

Core APIs and Use-Cases

1. TypedDict

TypedDict is used to define dictionaries with a specific set of keys and their associated types.

  from typing_extensions import TypedDict

  class User(TypedDict):
      name: str
      age: int
      is_active: bool

  user_data: User = {"name": "Alice", "age": 30, "is_active": True}

2. Literal

Literal allows you to specify exact values a variable can take.

  from typing_extensions import Literal

  def get_status(status: Literal["active", "inactive", "banned"]) -> str:
      return f"The user is {status}"

  print(get_status("active"))

3. Protocol

Protocol provides structural subtyping, useful for duck typing.

  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):
      print(greeter.greet(name))

  introducer = FriendlyGreeter()
  introduce(introducer, "Alice")

4. Final

Final designates a variable or method as immutable or marked as final to prevent overriding.

  from typing_extensions import Final

  MAX_USERS: Final = 100

5. @runtime_checkable

An annotation that ensures the Protocol can be checked at runtime using isinstance().

  from typing_extensions import Protocol, runtime_checkable

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

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

  greeter = FriendlyGreeter()
  print(isinstance(greeter, Greeter))  # True

6. Self (Python 3.11+)

The Self keyword lets you annotate methods that return the instance of their class.

  from typing_extensions import Self

  class MyClass:
      def set_value(self, value: int) -> Self:
          self.value = value
          return self

  obj = MyClass().set_value(100)

Example Application Utilizing Multiple Typing-Extensions APIs

Let’s create a simple UserManager application to demonstrate how different typing-extensions APIs work together.

  from typing_extensions import Protocol, TypedDict, Literal, runtime_checkable

  class User(TypedDict):
      username: str
      age: int
      status: Literal["active", "inactive", "banned"]

  @runtime_checkable
  class UserManagerProtocol(Protocol):
      def add_user(self, user: User) -> None:
          ...
      def get_user(self, username: str) -> User:
          ...

  class UserManager:
      def __init__(self):
          self.users: dict[str, User] = {}

      def add_user(self, user: User) -> None:
          self.users[user["username"]] = user

      def get_user(self, username: str) -> User:
          return self.users[username]

  user_manager: UserManagerProtocol = UserManager()
  user_manager.add_user({"username": "Alice", "age": 25, "status": "active"})
  retrieved_user = user_manager.get_user("Alice")
  print(retrieved_user)

Conclusion

The typing-extensions library is indispensable for developers who demand robust type hinting in Python, especially when working across Python versions. By using specific functionalities like TypedDict, Literal, and Protocol, you can create more maintainable and error-resistant code.