Flask-SQLAlchemy and Mypy

[tungol]

I'm opening this discussion for workaround to the previous discussed issues using mypy with flask-sqlalchemy:

#1327
#1186

In #1327, @fhd documented the workaround:

from typing import TYPE_CHECKING
...
if TYPE_CHECKING:
    from flask_sqlalchemy.model import Model
else:
    Model = db.Model

But he noted that this causes errors when using keyword arguments to the model classes. I spent a little while figuring this out, so I wanted to share my solution for that issue:

When you don't define an __init__ method on your class, it ends up with sqlalchemy.orm.decl_base._declarative_constructor as the __init__ method, which is then additionally wrapped by SQLAlchemy instrumentation functions. If you'd like to use keyword arguments, you should define a custom __init__ method which wraps this function:

from typing import TYPE_CHECKING
from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm.decl_base import _declarative_constructor

db = SQLAlchemy()

if TYPE_CHECKING:
    from flask_sqlalchemy.model import Model
else:
    Model = db.Model


class Thing(Model):
    __tablename___ = "things"
    name: Mapped[str]

    def __init__(self, *, name: str) -> None:
        _declarative_constructor(self, name=name)

With that, you can specify whatever mix of required and optional keywords you like. The signature for _declarative_constructor is: _declarative_constructor(self: Any, **kwargs: Any) -> None, so using kw-only args ensures that the interface is the same. Now Mypy will understand what kw-args are allowed for your class.