Introduction to typing-extensions

The typing-extensions module is an essential library for Python developers who want to stay ahead of the curve when working with type hints. It supplements the standard typing module with new features that are introduced in later versions of Python, making it backward-compatible with older versions. This module allows developers to adopt cutting-edge typing features without abandoning support for earlier Python interpreter versions.

Why Choose typing-extensions?

As Python evolves, new typing constructs are added to improve readability, enforce constraints, and facilitate better tooling. However, not all projects can immediately adopt the latest Python version. typing-extensions solves this dilemma by offering these features for older versions, so you can start using them today.

Key APIs in typing-extensions with Examples

1. TypedDict

TypedDict is used to define dictionary types with specific key-value pairs.

  from typing_extensions import TypedDict

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

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

2. Literal

Literal allows you to specify precise values a variable can take.

  from typing_extensions import Literal

  def greet(user_type: Literal["admin", "guest"]) -> str:
      if user_type == "admin":
          return "Welcome, Admin!"
      elif user_type == "guest":
          return "Hello, Guest!"

  print(greet("admin"))

3. Final

Prevent reassignment by marking variables or methods as constants with Final.

  from typing_extensions import Final

  MAX_USERS: Final = 100
  # MAX_USERS = 200  # This will raise a type-checking error

4. Annotated

Add metadata to type hints with Annotated.

  from typing_extensions import Annotated

  def process_data(data: Annotated[int, "This is a positive integer"]) -> str:
      return f"Data is: {data}"

5. Self

A placeholder for the instance type within class methods.

  from typing_extensions import Self

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

6. Required and NotRequired

Allow finer control over whether specific keys in a TypedDict are optional or mandatory.

  from typing_extensions import TypedDict, Required, NotRequired

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

  config: Config = {"host": "localhost", "port": 8080}

Real-World App Example

Let’s create a simple application that demonstrates the usage of typing-extensions.

  from typing_extensions import TypedDict, Literal, Annotated

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

  def display_user_info(user: Annotated[User, "User information object"]) -> None:
      print(f"User ID: {user['id']}")
      print(f"Name: {user['name']}")
      print(f"Role: {user['role']}")

  user1: User = {"id": 101, "name": "Alice", "role": "admin"}
  display_user_info(user1)

Conclusion

The typing-extensions library bridges the gap between immediate adoption of modern Python typing features and legacy Python compatibility. It offers developers the flexibility and power they need to write better, cleaner, and safer code. Start integrating typing-extensions today to future-proof your codebase!