Introduction to Typing-Extensions in Python

As Python continues to evolve, type annotations have become an essential part of writing reliable and maintainable code. However, some advanced typing features may not yet be available in older Python versions or even the current standard library. This is where typing-extensions comes in. The typing-extensions library enables you to use new typing features on older Python versions, ensuring backward compatibility while leveraging the latest advancements.

Why Use Typing-Extensions?

The typing-extensions package allows developers to access typing tools and constructs that:

• Are introduced in later Python releases.
• Provide experimental features that might not yet be finalized in the core library.
• Help maintain uniform type annotation support across Python versions.

Key Features and API Examples

Here are some key features and corresponding examples of typing-extensions:

1. Annotated

Annotated allows you to attach metadata to a type hint. This can be useful for validation, documentation, or runtime processing.

  from typing_extensions import Annotated

  Age = Annotated[int, "Should be a positive number"]

  def set_age(age: Age) -> None:
      if age < 0:
          raise ValueError("Age must be positive.")
      print(f"Age is set to {age}")

  set_age(25)  # Works fine
  # set_age(-5)  # Throws a ValueError

2. Literal

Literal restricts a function parameter to specific constant values.

  from typing_extensions import Literal

  def choose_color(color: Literal["red", "green", "blue"]) -> str:
      return f"You selected {color}"

  print(choose_color("red"))  # Valid
  # print(choose_color("yellow"))  # Raises a type checker error

3. TypedDict

TypedDict provides a way to define dictionaries with specific keys and value types.

  from typing_extensions import TypedDict

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

  user: User = {"name": "John", "age": 30}
  print(user)

4. Self

The Self type alias is used to annotate methods that return an instance of their own class.

  from typing_extensions import Self

  class Builder:
      def set_value(self, value: int) -> Self:
          self.value = value
          return self

  b = Builder().set_value(10)
  print(b.value)

5. Never

The Never type specifies a code path that should never happen.

  from typing_extensions import Never

  def handle_case(value: Never) -> None:
      raise ValueError("This code should never execute")

  # type checker will enforce that handle_case is never called

6. Final

Use Final to indicate that a variable or method is constant and should not be overridden or reassigned.

  from typing_extensions import Final

  MAX_SIZE: Final = 100
  # MAX_SIZE = 200  # Type checker error

7. Protocol

Protocol defines a structural interface, allowing you to specify required methods and attributes.

  from typing_extensions import Protocol

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

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

  def greet_user(greeter: Greeter, name: str) -> None:
      print(greeter.greet(name))

  greet_user(EnglishGreeter(), "Alice")

Complete App Example

Below is an example application that combines multiple features from typing-extensions.

  from typing_extensions import TypedDict, Literal, Annotated, Protocol

  class Product(TypedDict):
      name: str
      price: Annotated[float, "Should be a positive value"]

  class Formatter(Protocol):
      def format(self, product: Product) -> str:
          ...

  class SimpleFormatter:
      def format(self, product: Product) -> str:
          return f"{product['name']} - ${product['price']:,.2f}"

  def display_product(
      product: Product, formatter: Formatter, unit: Literal["USD", "EUR"]
  ) -> None:
      product_str = formatter.format(product)
      print(f"{product_str} ({unit})")

  product = {"name": "Laptop", "price": 1200.00}  # Valid Product
  formatter = SimpleFormatter()

  display_product(product, formatter, "USD")

Conclusion

The typing-extensions library is invaluable for developers who want access to the latest type hinting features while maintaining compatibility across Python versions. Its flexibility and wide range of utilities make it a must-have for writing clean, type-safe Python code, especially in collaborative or production environments.

Start incorporating typing-extensions into your projects today to unlock its full potential and elevate your development standards!