Introduction to Typing-Extensions

As Python continues to grow and evolve, the inclusion of type hints in Python 3.5 opened the door to safer, more understandable, and maintainable code. The typing-extensions package provides backports of typing features from newer Python versions, making them accessible to older Python versions and advancing the future of type hinting. In this guide, we’ll explore numerous powerful APIs provided by typing-extensions with examples, as well as how they can be utilized in real-world applications.

Key Features and APIs of Typing-Extensions

TypedDict

Create dictionaries with a fixed set of keys and their associated types. Ideal for specifying JSON-like structured data.

  from typing_extensions import TypedDict

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

  user: User = {'id': 1, 'name': 'Alice', 'active': True}

Literal

Specify exact, literal values as a type. Useful for controlling valid inputs.

  from typing_extensions import Literal

  def process_status(status: Literal['pending', 'completed', 'failed']) -> str:
    return f"Status is: {status}"
  
  print(process_status('completed'))

Annotated

Combine extra metadata with your type hints for better readability or tool integrations.

  from typing_extensions import Annotated

  def greet(name: Annotated[str, "Must be a valid string"]) -> str:
    return f"Hello, {name}!"
  
  print(greet("Bob"))

Final

Indicate that a variable, method, or class cannot be overridden or reassigned.

  from typing_extensions import Final

  PI: Final = 3.14159  # PI is constant
  # PI = 3.14  # This will raise an error

Protocol

Define structural subtyping, allowing classes to conform to a “protocol” without explicitly inheriting from it.

  from typing_extensions import Protocol

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

  class SimpleGreeter:
    def greet(self, name: str) -> str:
      return f"Hello, {name}!"

  def introduce(greeter: Greeter) -> None:
    print(greeter.greet("World"))

  greeter = SimpleGreeter()
  introduce(greeter)

Self

Useful for supporting recursive type hints within class methods.

  from typing_extensions import Self

  class Node:
    def set_next(self, next_node: Self) -> None:
      self.next_node = next_node

Never

Declare that a function will never return a value. Excellent for indicating errors or infinite loops.

  from typing_extensions import Never

  def error(msg: str) -> Never:
    raise RuntimeError(msg)

TypeAlias

Create aliases for complex types to improve readability.

  from typing_extensions import TypeAlias

  Vector: TypeAlias = tuple[float, float]

  def add(v1: Vector, v2: Vector) -> Vector:
    return (v1[0] + v2[0], v1[1] + v2[1])

@runtime_checkable

Enable runtime checks for Protocols.

  from typing_extensions import Protocol, runtime_checkable

  @runtime_checkable
  class Movable(Protocol):
    def move(self, x: int, y: int) -> None:
      ...

  class Robot:
    def move(self, x: int, y: int) -> None:
      print(f"Moving to: ({x}, {y})")

  robot = Robot()
  print(isinstance(robot, Movable))  # True

Real-World Application Example

Let’s create a small application that manages and processes user input and adheres to clean typing standards enforced by typing-extensions.

  from typing_extensions import TypedDict, Literal, Protocol, runtime_checkable

  class UserInput(TypedDict):
      username: str
      password: str

  @runtime_checkable
  class Validator(Protocol):
      def validate(self, data: UserInput) -> bool:
          ...

  class SimpleValidator:
      def validate(self, data: UserInput) -> bool:
          return bool(data['username'] and data['password'])

  def authenticate(input_data: UserInput, validator: Validator) -> Literal['Success', 'Failure']:
      if validator.validate(input_data):
          return 'Success'
      return 'Failure'

  user_data: UserInput = {
      "username": "test_user",
      "password": "secure_password"
  }

  validator = SimpleValidator()
  result = authenticate(user_data, validator)
  print(result)  # Output: Success

Conclusion

The typing-extensions library is an invaluable tool for Python developers aiming to implement advanced typing strategies while maintaining compatibility. By utilizing features like TypedDict, Protocol, Literal, and others, you can create robust and maintainable applications. Explore typing-extensions today and unlock the potential of type hinting!