Introduction to Typing Extensions

In the evolution of Python, type hints have been a significant addition, empowering developers with better tools for static typing. The typing-extensions library bridges the gap between the current Python typing module and upcoming features, offering backwards compatibility and future-ready APIs. Below, we’ll dive into the key features and numerous examples to help you get started effectively with this library.

Why Use Typing Extensions?

The typing-extensions library introduces experimental or new typing features before they’re added to the standard typing module in Python. It ensures that developers working on older versions of Python (e.g., Python 3.7, 3.8) can still leverage the latest improvements.

Essential APIs in typing-extensions

Here are several typing-extensions APIs, explained with practical examples:

1. Literal

Used to represent specific constant values as types.

  from typing_extensions import Literal

  def greet(mode: Literal["casual", "formal"]) -> str:
      if mode == "casual":
          return "Hey there!"
      elif mode == "formal":
          return "Good day!"
  
  print(greet("casual"))  # Output: Hey there!
  

2. TypedDict

Defines dictionaries with specific keys and value types.

  from typing_extensions import TypedDict

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

  user: User = {"id": 1, "name": "Alice"}
  

3. Protocol

Enables structural subtyping (duck typing) by defining protocols.

  from typing_extensions import Protocol

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

  class CasualGreeter:
      def greet(self):
          return "Yo!"

  def intro(greeter: Greeter) -> None:
      print(greeter.greet())

  greeter = CasualGreeter()
  intro(greeter)  # Output: Yo!
  

4. Final

Prevents a variable, method, or class from being overridden.

  from typing_extensions import Final

  PI: Final = 3.14159

  def calculate_circle_area(radius: float) -> float:
      return PI * (radius ** 2)

  print(calculate_circle_area(5))  # Output: 78.53975
  

5. Annotated

Adds metadata to a type for better introspection.

  from typing_extensions import Annotated

  def process_text(text: Annotated[str, "Input must be a valid string"]) -> str:
      return text.upper()

  print(process_text("hello"))  # Output: HELLO
  

6. Self

Allows type hinting for methods returning instances of their own class.

  from typing_extensions import Self

  class Builder:
      def set_name(self, name: str) -> Self:
          self.name = name
          return self

      def build(self) -> dict:
          return {"name": self.name}

  builder = Builder()
  result = builder.set_name("House").build()
  print(result)  # Output: {'name': 'House'}
  

Building a Simple App with typing-extensions

Let’s combine some of these APIs into a basic user-management app:

  from typing_extensions import TypedDict, Literal

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

  def create_user(user_id: int, name: str, role: Literal["admin", "editor", "viewer"]) -> User:
      return {"id": user_id, "name": name, "role": role}

  def get_greeting(user: User) -> str:
      if user["role"] == "admin":
          return f"Welcome, Administrator {user['name']}!"
      elif user["role"] == "editor":
          return f"Hello Editor {user['name']}, ready to create?"
      else:
          return f"Hello Viewer {user['name']}, enjoy your reading!"

  user1 = create_user(1, "Alice", "admin")
  print(get_greeting(user1))  # Output: Welcome, Administrator Alice!
  

Conclusion

The typing-extensions library is a robust tool for enriching your Python projects with modern type hints. By leveraging its various features and APIs, you can write cleaner, smarter, and more maintainable code. Start using typing-extensions today to adopt the future of Python typing!