Introduction to typing-extensions

typing-extensions is a Python package that serves as a forward-compatibility bridge, offering features and APIs that may eventually end up in the standard typing module. It provides developers with access to experimental and future typing functionalities while preserving compatibility with older Python versions.

In this blog, we’ll explore how the typing-extensions library enhances your code and supports modern, maintainable workflows. We’ll also show code examples ranging from basic to advanced features, as well as an example application implementing several of these APIs.

Why Use typing-extensions?

• Access to experimental typing APIs.
• Backwards compatibility with Python versions that do not support the latest typing features.
• Enhance the clarity and maintainability of your code with modern type hints.

Key APIs and Examples

TypedDict: Type-Safe Dictionaries

TypedDict allows you to define type-safe dictionaries wherein you explicitly define the expected keys and their corresponding value types.

  from typing_extensions import TypedDict

  class Person(TypedDict):
      name: str
      age: int

  def greet(person: Person) -> None:
      print(f"Hello, {person['name']}. You are {person['age']} years old.")

  person_data = {"name": "Alice", "age": 30}
  greet(person_data)

Protocol: Structural Subtyping

The Protocol class enables structural typing, allowing you to define interfaces a class can adhere to without formal inheritance.

  from typing_extensions import Protocol

  class Greetable(Protocol):
      def greet(self) -> str:
          ...

  class Person:
      def __init__(self, name: str):
          self.name = name

      def greet(self) -> str:
          return f"Hi, I am {self.name}!"

  def introduce(entity: Greetable) -> None:
      print(entity.greet())

  alice = Person("Alice")
  introduce(alice)

Final: Immutable Variables

Final ensures that a variable or attribute is immutable once assigned, improving code consistency and correctness.

  from typing_extensions import Final

  PI: Final = 3.14159

  # PI = 3.14  # This will raise a type checker error
  print(f"Value of PI: {PI}")

Literal: Enforcing Specific Values

With Literal, you can limit arguments or variables to predefined constant values.

  from typing_extensions import Literal

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

  get_status("success")
  # get_status("pending")  # This will fail type checking

Advanced: overload, Custom Types, and More

Use @overload to define multiple signatures for a single function, and explore end-to-end examples using multiple features together.

  from typing_extensions import overload

  @overload
  def describe(entity: int) -> str: ...
  @overload
  def describe(entity: str) -> str: ...

  def describe(entity):
      if isinstance(entity, int):
          return f"A number: {entity}"
      elif isinstance(entity, str):
          return f"A string: {entity}"
      else:
          raise TypeError("Unsupported type")

  print(describe(42))
  print(describe("hello"))

Real-World Example Application

Here is a mini-application that utilizes several typing-extensions APIs to create a user management system.

  from typing_extensions import TypedDict, Protocol, Final

  class User(TypedDict):
      id: int
      username: str
      is_active: bool

  class HasId(Protocol):
      id: int

  MAX_USERS: Final = 100  # Ensuring immutability

  users = []

  def add_user(user: User) -> None:
      if len(users) >= MAX_USERS:
          raise ValueError("Max users reached.")
      users.append(user)

  def delete_user(user: HasId) -> None:
      global users
      users = [u for u in users if u["id"] != user.id]

  new_user = User(id=1, username="Alice", is_active=True)
  add_user(new_user)
  print(users)
  delete_user(new_user)
  print(users)

In this example, we’ve leveraged TypedDict for defining user structures, Protocol for object interface checks, and Final for constants. The result is cleaner and more robust code.

Conclusion

The typing-extensions library provides critical tools for developers aiming to write type-hinted, future-proof, and backward-compatible Python code. By utilizing features like TypedDict, Protocol, Literal, and others, you can significantly enhance the quality and maintainability of your projects.

So why wait? Start integrating typing-extensions into your projects today and enjoy the benefits of modern Python typing while staying compatible with older versions.