Welcome to the Complete Guide to Typing-Extensions!

In the ever-evolving landscape of Python programming, type hinting has become a critical tool to improve code readability, maintainability, and reliability. While the Python standard library includes a typing module for type annotations, the typing-extensions package extends its capabilities, introducing experimental and forward-compatible type hints to supercharge your applications.

Getting Started with Typing-Extensions

The typing-extensions module is particularly useful when you need support for newer type hinting features in older versions of Python. Install the library using pip:

  pip install typing-extensions

Key APIs and Their Usage

Let’s dive into some of the most essential and commonly used APIs provided by typing-extensions, along with practical code snippets!

1. TypedDict

TypedDict allows you to define dictionary-like objects with strongly-typed keys and values.

  from typing_extensions import TypedDict

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

  user: User = {"id": 1, "name": "Alice", "email": "alice@example.com"}
  print(user["email"])  # Output: alice@example.com

2. Protocol

Define interfaces similar to those in statically-typed languages.

  from typing_extensions import Protocol

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

  class Human:
      def greet(self) -> str:
          return "Hello!"

  def say_hello(greeter: Greetable) -> None:
      print(greeter.greet())

  person = Human()
  say_hello(person)  # Output: Hello!

3. Literal

Define specific constant values for type hinting.

  from typing_extensions import Literal

  def get_status(code: Literal[200, 404, 500]) -> str:
      if code == 200:
          return "Success"
      elif code == 404:
          return "Not Found"
      elif code == 500:
          return "Server Error"

  print(get_status(200))  # Output: Success

4. Final

Make variables or methods immutable and prevent overriding in subclasses.

  from typing_extensions import Final

  MAX_CONNECTIONS: Final = 100

  print(MAX_CONNECTIONS)  # Output: 100

5. @runtime_checkable

Check protocol compliance at runtime.

  from typing_extensions import Protocol, runtime_checkable

  @runtime_checkable
  class Logger(Protocol):
      def log(self, message: str) -> None: ...

  class ConsoleLogger:
      def log(self, message: str) -> None:
          print(message)

  logger = ConsoleLogger()
  if isinstance(logger, Logger):
      logger.log("This is a log message!")  # Output: This is a log message!

6. Concatenate

Compose additional arguments in callable typing.

  from typing_extensions import Concatenate, Callable, ParamSpec

  P = ParamSpec("P")

  def log_function_call(callback: Callable[Concatenate[str, P], None]) -> Callable[P, None]:
      def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
          print("Calling function...")
          callback("Extra Argument", *args, **kwargs)
      return wrapper

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

  greet("John")  # Output: Calling function...
                 #         Extra Argument: Hello, John!

Application Example Combining These APIs

Here’s a small app that utilizes multiple APIs from typing-extensions to create a lightweight user management system:

  from typing_extensions import TypedDict, Protocol, runtime_checkable, Literal

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

  @runtime_checkable
  class Database(Protocol):
      def add_user(self, user: User) -> None: ...
      def remove_user(self, user_id: int) -> None: ...
      def list_users(self) -> list[User]: ...

  class InMemoryDatabase:
      def __init__(self):
          self.users: list[User] = []

      def add_user(self, user: User) -> None:
          self.users.append(user)

      def remove_user(self, user_id: int) -> None:
          self.users = [u for u in self.users if u["id"] != user_id]

      def list_users(self) -> list[User]:
          return self.users

  db = InMemoryDatabase()
  db.add_user({"id": 1, "name": "Alice", "role": "admin"})
  db.add_user({"id": 2, "name": "Bob", "role": "guest"})

  if isinstance(db, Database):
      print("Users:", db.list_users())
      
      db.remove_user(2)
      print("After removal:", db.list_users())
      
      # Output:
      # Users: [{'id': 1, 'name': 'Alice', 'role': 'admin'}, {'id': 2, 'name': 'Bob', 'role': 'guest'}]
      # After removal: [{'id': 1, 'name': 'Alice', 'role': 'admin'}]

Conclusion

The typing-extensions library is a treasure trove for Python developers aiming to write scalable, robust, and type-safe code. Whether you’re working on small projects or large systems, these tools will simplify your type hints and make interacting with dynamic Python code much safer.

Explore these APIs in your projects to see how much consistency they can bring to your workflow. Start small, and gradually incorporate more advanced tools like Protocol, TypedDict, and Concatenate.