Mastering typing-extensions in Python

The typing-extensions module in Python is a powerful tool for developers who use type hints to write cleaner, more robust, and maintainable Python code. In some cases, the typing features available in the standard library may be insufficient, especially when working with older versions of Python. This is where typing-extensions steps in, offering backports of new type-hinting features introduced in newer Python versions.

Key Features and APIs of typing-extensions

1. Literal

The Literal type allows you to specify that a variable or a function parameter must have a specific literal value.

  from typing_extensions import Literal

  def greet(role: Literal['admin', 'user', 'guest']):
      if role == 'admin':
          return "Welcome, Admin!"
      elif role == 'user':
          return "Welcome, User!"
      elif role == 'guest':
          return "Welcome, Guest!"

  print(greet('admin'))  # Output: Welcome, Admin!

2. TypedDict

TypedDict allows you to define dictionaries with a fixed set of keys and associated value types.

  from typing_extensions import TypedDict

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

  user: UserInfo = {"name": "Alice", "age": 30, "is_active": True}
  print(user)

3. Final

The Final keyword marks a variable or a method as immutable or un-overridable.

  from typing_extensions import Final

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

  print(API_URL)
  # API_URL cannot be reassigned or altered

4. Protocol

Protocols allow you to define structural subtypes by specifying the methods or attributes that a class must implement.

  from typing_extensions import Protocol

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

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

  def let_it_fly(flyer: Flyer):
      print(flyer.fly())

  bird = Bird()
  let_it_fly(bird)

5. Annotated

Annotated allows adding metadata to type hints.

  from typing_extensions import Annotated

  def process_data(data: Annotated[int, "positive integer"]):
      if data > 0:
          print("Data processed:", data)
      else:
          raise ValueError("Data must be a positive integer.")

  process_data(5)  # Output: Data processed: 5

6. Self

The Self type is used to annotate methods that return the type of the class they belong to.

  from typing_extensions import Self

  class Builder:
      def __init__(self):
          self.parts = []

      def add_part(self, part: str) -> Self:
          self.parts.append(part)
          return self

      def build(self) -> str:
          return " + ".join(self.parts)

  builder = Builder().add_part("Part A").add_part("Part B")
  print(builder.build())  # Output: Part A + Part B

Example Application Using typing-extensions

Let’s build a simple user management app using various features of typing-extensions.

  from typing_extensions import Literal, TypedDict, Protocol, Final

  # Constants
  BASE_URL: Final = "https://api.example.com"

  # Define TypedDict for user data
  class User(TypedDict):
      username: str
      role: Literal["admin", "user", "guest"]
      active: bool

  # Protocol for a notifier service
  class Notifier(Protocol):
      def notify(self, user: User, message: str) -> None:
          pass

  # Concrete implementation of Notifier Protocol
  class EmailNotifier:
      def notify(self, user: User, message: str) -> None:
          print(f"Sending email to {user['username']} with message: {message}")

  def process_user(user: User, notifier: Notifier):
      if user['active']:
          notifier.notify(user, "Welcome back!")
      else:
          notifier.notify(user, "Your account is inactive.")

  # Sample user and notifier
  user_data: User = {"username": "john_doe", "role": "admin", "active": True}
  notifier_service = EmailNotifier()

  process_user(user_data, notifier_service)

Conclusion

The typing-extensions module is an indispensable tool for developers who thrive on writing type-safe Python code. By leveraging its diverse features like Literal, TypedDict, Final, Protocol, and more, you can build more predictable and maintainable codebases. The examples provided above highlight the versatility and practical applications of this library, making it easier to adopt type hinting in any Python project.