What is Typing-Extensions?

typing-extensions is a must-have Python library that brings forward-compatibility to your type hinting needs. It backports types and utilities from newer versions of Python’s typing module to older Python versions, enabling developers to utilize the latest typing features without upgrading their Python runtime. Whether you’re maintaining legacy code or writing modern Python, typing-extensions is indispensable.

Why Should You Use Typing Extensions?

Typing not only improves code readability and maintainability but also shortens debugging and development time. However, Python’s typing module evolves independently of older Python versions. typing-extensions bridges the gap by delivering these new features seamlessly.

Key APIs in Typing-Extensions with Examples

1. Literal

Allows specifying that a certain variable or function can only take on specific literal values.

  from typing_extensions import Literal

  def get_status(status: Literal["success", "failure", "pending"]) -> str:
      return status

  print(get_status("success"))  # Valid
  # print(get_status("unknown"))  # Raises a type checker error

2. Final

Prevents reassignment of a variable or subclassing a class.

  from typing_extensions import Final

  PI: Final = 3.14159  # Cannot be reassigned

  class BaseClass:
      pass

  class DerivedClass(BaseClass):  # Valid
      pass

  class ImmutableClass(Final):
      pass

  # class SubImmutableClass(ImmutableClass):  # Error: Cannot inherit from final class

3. TypedDict

Enables defining dicts with a specific shape for keys and values.

  from typing_extensions import TypedDict

  class User(TypedDict):
      username: str
      email: str
      age: int

  user: User = {
      "username": "john_doe",
      "email": "john@example.com",
      "age": 30
  }

  print(user["username"])  # john_doe

4. Protocol

Defines structural subtyping, ensuring objects confirm to specific behavior.

  from typing_extensions import Protocol

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

  class HelloWorld:
      def greet(self) -> str:
          return "Hello, World!"

  def greet_user(greeter: Greeter):
      print(greeter.greet())

  greet_user(HelloWorld())

5. Self

Used in type hints to indicate that the method returns the instance of its 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().set_name("MyApp").build()
  print(builder)  # {'name': 'MyApp'}

Building a Mini Typed API Using Typing-Extensions

Let’s combine the above APIs to create a mini employee management application.

  from typing_extensions import TypedDict, Final, Literal, Self

  EmployeeID: Final = "EMP-"  # Final constant

  class Employee(TypedDict):
      id: str
      name: str
      role: Literal["Developer", "Manager", "HR"]

  class EmployeeManager:
      def __init__(self):
          self.employees: dict[str, Employee] = {}

      def add_employee(self, name: str, role: Literal["Developer", "Manager", "HR"]) -> Self:
          emp_id = f"{EmployeeID}{len(self.employees) + 1}"
          self.employees[emp_id] = {"id": emp_id, "name": name, "role": role}
          return self

      def get_employee(self, emp_id: str) -> Employee:
          return self.employees[emp_id]

  # Example usage
  manager = EmployeeManager()
  manager.add_employee("Alice", "Developer").add_employee("Bob", "Manager")
  print(manager.get_employee("EMP-1"))  # Output: {'id': 'EMP-1', 'name': 'Alice', 'role': 'Developer'}

Final Thoughts

Using typing-extensions, you can write robust, maintainable, and future-proof Python code. It ensures that new type hints are available in older Python versions, allowing developers to utilize cutting-edge typing features effortlessly. Start using typing-extensions, and see how your development cycles improve dramatically.