Typing Extensions: Unlock Advanced Typing Features in Python

Python’s dynamic typing system is one of its best features, but sometimes you need more precise control to write clean, maintainable, and error-free code. The typing-extensions library bridges the gap between older Python versions and newer type features introduced in modern Python releases. It offers forward-compatible typing features, letting you use new type constructs even if you’re running an older Python version.

Getting Started with Typing Extensions

To use typing-extensions, you must first install it. You can do so via pip:

  pip install typing-extensions

Now you’re ready to explore its features!

Key Features of Typing Extensions

Here are some of the most useful types and APIs provided by typing-extensions, along with code examples for each.

1. Literal

The Literal type lets you specify that a variable or parameter can only take certain predefined values:

  from typing_extensions import Literal

  def set_status(status: Literal['online', 'offline', 'away']):
      print(f"Status set to {status}")

  set_status('online')  # Valid
  set_status('busy')    # Raises a type-checking error

2. TypedDict

TypedDict allows you to define dictionary-like structures with specific key-value types.

  from typing_extensions import TypedDict

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

  user: UserInfo = {
      'name': 'Alice',
      'age': 25,
  }
  

3. Protocol

The Protocol class allows you to specify structural subtyping by defining what methods or attributes a type must implement.

  from typing_extensions import Protocol

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

  class Bird:
      def fly(self) -> None:
          print("Bird is flying")

  def start_flying(flyer: Flyer):
      flyer.fly()

  start_flying(Bird())  # Works because Bird implements the fly() method

4. Required and NotRequired

Required and NotRequired can be used in conjunction with TypedDict to specify whether fields are required or optional.

  from typing_extensions import TypedDict, Required, NotRequired

  class Config(TypedDict):
      host: Required[str]
      port: NotRequired[int]

  config: Config = {
      'host': 'localhost',
      # 'port' is optional
  }
  

5. Self

The Self type enables you to annotate methods that return the same class as the one they belong to.

  from typing_extensions import Self

  class Chainable:
      def set_name(self, name: str) -> Self:
          self.name = name
          return self
      
      def set_age(self, age: int) -> Self:
          self.age = age
          return self

  user = Chainable().set_name("Alice").set_age(25)
  

6. Other Advanced APIs

• Annotated: Add metadata to type hints.
• Final: Mark variables or methods as immutable or non-overridable.
• Concatenate: Combine multiple argument types for callable annotations.

Building a Mini App Using Typing Extensions

Here’s a simple example of a user management system combining several features of typing-extensions.

  from typing_extensions import Literal, TypedDict, Protocol, Self

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

  class Authenticatable(Protocol):
      def login(self, username: str, password: str) -> bool:
          ...

  class UserService:
      def __init__(self):
          self.users: list[User] = []

      def add_user(self, user_id: int, name: str, role: Literal['admin', 'user']) -> Self:
          self.users.append({'id': user_id, 'name': name, 'role': role})
          return self

      def get_users(self) -> list[User]:
          return self.users

  class AuthService:
      def login(self, username: str, password: str) -> bool:
          # Placeholder logic
          return username == 'admin' and password == 'admin'

  # Example App
  user_service = UserService()
  user_service.add_user(1, 'Alice', 'admin').add_user(2, 'Bob', 'user')
  print(user_service.get_users())

  auth_service = AuthService()
  print(auth_service.login('admin', 'admin'))  # Output: True

Conclusion

The typing-extensions library is an invaluable tool for Python developers seeking to leverage advanced typing features. Whether you’re writing safer code or building more maintainable systems, this library has you covered. Try it in your next project and experience the benefits yourself!