python-typing-idioms

Python typing idioms

Modern typed Python is a different language than typed Python five years ago. PEP 695 (Python 3.12) made generics and type aliases first-class. Protocol finally displaced ABC for most interface use cases. The Self type lets @classmethod constructors and builder-style methods type themselves correctly.

This skill encodes the idioms that hold up in 2026 typed Python.

When to use this skill

Apply these rules whenever you're:

• Writing a new module with type annotations
• Adding types to existing code
• Designing a class hierarchy, especially one used as a port/interface
• Building cohesion methods (from_X, to_Y)
• Defining ID types or other domain primitives
• Working with FastAPI Depends (the Annotated[X, Depends(...)] pattern)

The rules

1. Protocol for interfaces; ABC only when you need shared implementation

abc.ABC couples interface to inheritance. Protocol types by shape, which matches Python's duck typing and lets unrelated classes satisfy the contract without inheriting.

from typing import Protocol

class Notifier(Protocol):
    async def send(self, to: str, body: str) -> None: ...


class EmailNotifier:                      # no Notifier in bases
    async def send(self, to: str, body: str) -> None: ...


class SMSNotifier:
    async def send(self, to: str, body: str) -> None: ...


async def notify(notifier: Notifier, to: str, body: str) -> None:
    await notifier.send(to, body)


await notify(EmailNotifier(), "[email protected]", "hi")
await notify(SMSNotifier(), "+1...", "hi")

Use ABC only when you genuinely need partial implementation that subclasses must extend. For pure interfaces (the common case), Protocol.

2. Self for classmethod constructors and self-returning methods

Self (PEP 673, Python 3.11+) lets a method return "the subclass that called me" without TypeVar ceremony.

from typing import Self
from dataclasses import dataclass


@dataclass(frozen=True, slots=True, kw_only=True)
class Money:
    amount: Decimal
    currency: str

    @classmethod
    def zero(cls, currency: str) -> Self:
        return cls(amount=Decimal("0"), currency=currency)

    def with_amount(self, amount: Decimal) -> Self:
        return type(self)(amount=amount, currency=self.currency)