Introduction to Typing Extensions

typing-extensions is a robust library designed to complement the standard typing module in Python. It enables using new typing features even in older Python versions, making your code more adaptable and forward-compatible. Whether you are working with Python versions that don’t yet have the latest features or need polyfills for typing constructs, typing-extensions can be a lifesaver.

Core Features and APIs of Typing Extensions

The typing-extensions library extends functionality by introducing additional APIs and utilities. Here are some of its most useful features:

1. Protocol

Protocols define structural subtyping (or “duck typing”). A class that implements all the methods and properties declared in the protocol is compatible with that protocol.

    from typing_extensions import Protocol

    class SupportsWrite(Protocol):
        def write(self, data: str) -> None:
            pass

    class FileWriter:
        def write(self, data: str) -> None:
            print(f"Data written: {data}")

    def save_data(writer: SupportsWrite, data: str) -> None:
        writer.write(data)

    # Usage
    fw = FileWriter()
    save_data(fw, "Hello, Typing Extensions!")

2. TypedDict

TypedDict enables dictionary-like objects with a fixed set of keys and value types, making your code safer and easier to debug.

    from typing_extensions import TypedDict

    class Movie(TypedDict):
        title: str
        year: int

    my_movie: Movie = {"title": "Inception", "year": 2010}

3. Literal

Literal allows specifying exact values a variable can accept.

    from typing_extensions import Literal

    def set_status(status: Literal["success", "failure"]) -> None:
        print(f"Status set to: {status}")

    set_status("success")
    # set_status("unknown")  # Fails static type checking

4. Final

Use Final to declare variables or methods that shouldn’t be overridden or reassigned.

    from typing_extensions import Final

    MAX_USERS: Final = 100

    class Base:
        def greet(self) -> None:
            print("Hello!")

    class Derived(Base):
        def greet(self) -> None:
            print("Welcome!")  # Type checkers flag this as an error if marked Final

5. Annotated

Annotated allows you to associate metadata with a type hint.

    from typing_extensions import Annotated

    UserID = Annotated[int, "The ID of the user"]

    def get_user(user_id: UserID) -> str:
        return f"User {user_id}"

6. Concatenate

Allows defining callable types that concatenate arguments.

    from typing_extensions import Concatenate, Protocol

    class Logger(Protocol):
        def log(self, message: str, /, *values: object) -> None:
            pass

    def bind_logger(
        logger: Logger,
    ) -> Concatenate[str, None]:
        pass

7. Self

Reference the current class type within method signatures.

    from typing_extensions import Self

    class FluentStringBuilder:
        def __init__(self) -> None:
            self.parts = []

        def add(self, part: str) -> Self:
            self.parts.append(part)
            return self

        def build(self) -> str:
            return "".join(self.parts)

    builder = FluentStringBuilder()
    message = builder.add("Hello, ").add("World!").build()
    print(message)  # Outputs: "Hello, World!"

Building an App with Typing Extensions

Now let’s build a simplified logging app that demonstrates multiple Typing Extensions APIs like Literal, Protocol, and Final.

    from typing_extensions import Final, Literal, Protocol

    LogLevel = Literal["INFO", "DEBUG", "ERROR"]

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

    class ConsoleLogger:
        APP_NAME: Final[str] = "MyApp"

        def log(self, level: LogLevel, message: str) -> None:
            print(f"[{self.APP_NAME}] {level}: {message}")

    def process_data(logger: Logger, data: int) -> None:
        if data > 0:
            logger.log("INFO", f"Processing data: {data}")
        else:
            logger.log("ERROR", "No valid data to process.")

    # Usage
    logger = ConsoleLogger()
    process_data(logger, 42)

This example app shows how we can use Protocol for interface definitions, Literal for fixed argument values, and Final for constants, creating a type-safe and reliable Python application.

Conclusion

Incorporating typing-extensions into your Python projects provides a versatile and backward-compatible way to adopt Python’s type-hinting features. By leveraging APIs like Protocol, Literal, TypedDict, and others, you can write cleaner, more maintainable, and predictable code. Whether you’re using it for a small script or a large application, typing-extensions significantly enhances the developer experience and code quality.