Enhance Your Python Code with Typing Extensions: A Comprehensive Guide

Python’s dynamic typing makes it a powerful and convenient language, but it can sometimes lead to ambiguity when maintaining a growing codebase. This is where the typing-extensions library comes in. The typing-extensions package provides backports of some features from the typing module that are available in newer Python versions but may not yet be available in your current runtime.

Why Use typing-extensions?

With typing-extensions, you can adopt new type-hinting features without waiting for your application to upgrade to the latest Python release. This package is especially useful in large projects where compatibility with multiple Python versions is a must.

Key APIs in typing-extensions with Examples

Below is a collection of APIs provided by typing-extensions, accompanied by code snippets so you can see them in action.

TypedDict

The TypedDict class allows you to define dictionary types with specific key-value types.

  from typing_extensions import TypedDict

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

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

Literal

Define literal types where specific string or numeric values are allowed:

  from typing_extensions import Literal

  def greet(language: Literal["en", "es", "fr"]) -> str:
      if language == "en":
          return "Hello"
      elif language == "es":
          return "Hola"
      elif language == "fr":
          return "Bonjour"

  print(greet("en"))  # Outputs: Hello

Protocol

The Protocol class allows you to define structural subtyping (as opposed to nominal subtyping):

  from typing_extensions import Protocol

  class SupportsSpeak(Protocol):
      def speak(self) -> str:
          ...

  class Dog:
      def speak(self) -> str:
          return "woof"

  def make_speakable(animal: SupportsSpeak) -> str:
      return animal.speak()

  pet = Dog()
  print(make_speakable(pet))  # Outputs: woof

Self

With Self, you can annotate methods that return an instance of their 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().set_name("Alice").build()
  print(builder)  # Outputs: {'name': 'Alice'}

Concatenate and ParamSpec

These are useful for higher-order functions that need precise type annotations.

  from typing_extensions import Concatenate, ParamSpec
  from typing import Callable

  P = ParamSpec('P')

  def add_logging(func: Callable[Concatenate[str, P], None]) -> Callable[P, None]:
      def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
          print("Log: Calling", func.__name__)
          func("Added log", *args, **kwargs)
      return wrapper

  @add_logging
  def greet(log: str, name: str) -> None:
      print(f"{log}: Hello, {name}!")

  greet("Alice")  # Outputs log messages and greeting

Building a Sample Application Using typing-extensions

Let’s create a small app that demonstrates the use of several typing-extensions APIs:

  from typing_extensions import TypedDict, Literal, Protocol, Self

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

  class CanGreet(Protocol):
      def greet(self, user: User) -> str:
          ...

  class Greeter:
      def __init__(self, language: Literal["en", "es"]) -> None:
          self.language = language

      def greet(self, user: User) -> str:
          if self.language == "en":
              return f"Hello {user['name']}!"
          elif self.language == "es":
              return f"Hola {user['name']}!"

  class App:
      def __init__(self) -> Self:
          self.greeters = {"en": Greeter("en"), "es": Greeter("es")}
          return self

      def run(self) -> None:
          user: User = {"id": 1, "name": "Alice", "role": "admin"}
          greeter = self.greeters.get("en")
          if greeter:
              print(greeter.greet(user))

  app = App().run()

Conclusion

The typing-extensions library provides powerful tools to enhance type hints in Python, especially when you’re working with older Python versions. Adopting these utilities in your code can significantly improve its readability, maintainability, and reliability. Try incorporating typing-extensions into your next project!