the declarative_base() function was a convenient approach at the time it was created, however it is not in line with current Python practices. The comments on python/typing#1020 indicate that typing tools have no plans to support this pattern in any way right now, and I also get the vibe, based on the comments, as well as that the actual mypy hook for dynamic classes refers to our own API as the example, that we are the only ones doing this in any prominent way.

on top of that, the declarative_base()'s reliance on metaclasses, which are usually unnecessary these days now that we have __init_subclass__(), has always been a burden on users who were often trying to use their own metaclasses, as well as that it caused problems we had to fix with end-user classes that used __init_subclass__() or __class_getitem__().

on top of that we already have many other ways to mark classes as mapped, most conveniently the @registry.mapped decorator.

However, having a Base class is still a very handy pattern, I still find myself preferring it, and the whole world uses it. We'd also like to get rid of the metaclass requirement without breaking backwards compatibility.

Turns out that with the current API and __init_subclass__(), making a new declarative base that isn't too much trouble is stupidly easy, though it does require two lines on the part of the end user rather than one to create, like this:

class DeclarativeBase(MappedBase):
    registry: ClassVar["registry"]
    metadata: ClassVar[MetaData]
    __mapper__: ClassVar[Mapper]
    __table__: Optional[FromClause]

    if typing.TYPE_CHECKING:
        def __init__(self, **kw: Any):
            ...

    def __init_subclass__(cls) -> None:
        if DeclarativeBase in cls.__bases__:
            cls.registry = registry()
            cls.metadata = cls.registry.metadata
        else:
            cls.registry.mapped(cls)

so end user code does:

from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

that's your Base. mypy no longer complains and you also have a nice place to put custom mixin logic (that works right now too).

so far there's two things we change in the API and we have basically everything we want, except for fully-typed init:

1. mapped_column constructor
2. new declarative base as above