Typing Extensions: Extending Python’s Typing Capabilities

Python’s typing module has become an essential part of writing modern, type-safe Python code. However, as Python evolves, new typing features are often introduced in successive versions, leaving developers using older Python versions needing a way to access them. This is where typing-extensions steps in as a backport library, providing access to new typing features across Python versions.

In this blog, we’ll uncover the power of typing-extensions, exploring its most useful API offerings with practical examples. You’ll also discover how to employ these tools in a small application.

1. From Literal to Annotated: Embrace Typing Versatility

Literal

The Literal type helps you restrict a variable to specific literal values.

  from typing_extensions import Literal

  def greet_user(user_type: Literal["admin", "guest"]) -> str:
      if user_type == "admin":
          return "Welcome, Admin!"
      elif user_type == "guest":
          return "Hello, Guest!"

  print(greet_user("admin"))  # Output: Welcome, Admin!

Annotated

Annotated enriches type hints with additional metadata, making them more descriptive.

  from typing_extensions import Annotated

  Age = Annotated[int, "User's age in years"]
  def set_age(age: Age) -> str:
      return f"Age set to {age} years."

  print(set_age(25))  # Output: Age set to 25 years.

2. Enhanced Container Typing

Self

Use Self for method chaining, ensuring precise types for fluent APIs.

  from typing_extensions import Self

  class FluentBuilder:
      def __init__(self):
          self.data = {}

      def set_key(self, key: str, value: str) -> Self:
          self.data[key] = value
          return self

      def build(self) -> dict:
          return self.data

  builder = FluentBuilder()
  config = builder.set_key("host", "localhost").set_key("port", "8080").build()
  print(config)  # Output: {'host': 'localhost', 'port': '8080'}

TypedDict

Define dictionaries with a fixed structure using TypedDict.

  from typing_extensions import TypedDict

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

  user: User = {"id": 1, "name": "Alice"}
  print(user)  # Output: {'id': 1, 'name': 'Alice'}

3. Asynchronous API Support

Awaitable and AsyncContextManager

Define asynchronous tasks cleanly.

  from typing_extensions import Awaitable, AsyncContextManager
  import asyncio

  class AsyncFile(AsyncContextManager):
      async def __aenter__(self):
          print("Opening file")
          return self

      async def __aexit__(self, exc_type, exc, tb):
          print("Closing file")

  async def async_main() -> Awaitable[None]:
      async with AsyncFile():
          print("Processing file")
          
  asyncio.run(async_main())

Application Example

User Registration System

Leveraging typing-extensions for robust error handling and user modeling.

  from typing_extensions import Literal, TypedDict, Self

  class User(TypedDict):
      id: int
      name: str
      role: Literal["admin", "member"]

  class UserManager:
      def __init__(self):
          self.users = []

      def add_user(self, user: User) -> Self:
          self.users.append(user)
          return self

      def get_admins(self) -> list[User]:
          return [user for user in self.users if user["role"] == "admin"]

  manager = UserManager()
  manager.add_user({"id": 1, "name": "Alice", "role": "admin"})
  manager.add_user({"id": 2, "name": "Bob", "role": "member"})

  admins = manager.get_admins()
  print(admins)  # Output: [{'id': 1, 'name': 'Alice', 'role': 'admin'}]

Conclusion

The typing-extensions module bridges the gap for developers who want cutting-edge type hints while maintaining backward compatibility with different Python versions. By incorporating these APIs into your Python projects, you can enhance readability, improve error-checking, and accelerate development.