sqlmodel-mypy-plugin 0.18.0__tar.gz → 0.19.1__tar.gz

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/.gitignore

@@ -21,3 +21,5 @@ ENV/
 
 dist/
 build/
+
+excl-*

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Artem
+Copyright (c) 2026 sertione
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: sqlmodel-mypy-plugin
-Version: 0.18.0
+Version: 0.19.1
 Summary: Mypy plugin for SQLModel (better constructor/Field typing).
 Project-URL: Homepage, https://github.com/sertione/sqlmodel-mypy-plugin
 Project-URL: Repository, https://github.com/sertione/sqlmodel-mypy-plugin
 Project-URL: Issues, https://github.com/sertione/sqlmodel-mypy-plugin/issues
 Project-URL: Changelog, https://github.com/sertione/sqlmodel-mypy-plugin/releases
-Author: Artem
+Author: sertione
 License: MIT License
         
-        Copyright (c) 2026 Artem
+        Copyright (c) 2026 sertione
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
@@ -30,7 +30,7 @@ License: MIT License
         SOFTWARE.
 License-File: LICENSE
 Keywords: mypy,plugin,pydantic,sqlalchemy,sqlmodel,typing
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -52,8 +52,6 @@ Mypy plugin that improves type checking for [`SQLModel`](https://github.com/fast
 
 Early/experimental. Implemented scope (supported today):
 
-Planned work is tracked in [`ROADMAP.md`](ROADMAP.md).
-
 - Generate correct `__init__` / `model_construct` signatures for SQLModel models:
   - treat `sqlmodel.Field(...)` required/optional correctly
   - accept `sqlmodel.Relationship(...)` kwargs for `table=True` models

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/README.md

@@ -6,8 +6,6 @@ Mypy plugin that improves type checking for [`SQLModel`](https://github.com/fast
 
 Early/experimental. Implemented scope (supported today):
 
-Planned work is tracked in [`ROADMAP.md`](ROADMAP.md).
-
 - Generate correct `__init__` / `model_construct` signatures for SQLModel models:
   - treat `sqlmodel.Field(...)` required/optional correctly
   - accept `sqlmodel.Relationship(...)` kwargs for `table=True` models

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlmodel-mypy-plugin"
-version = "0.18.0"
+version = "0.19.1"
 description = "Mypy plugin for SQLModel (better constructor/Field typing)."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { file = "LICENSE" }
-authors = [{ name = "Artem" }]
+authors = [{ name = "sertione" }]
 keywords = ["mypy", "plugin", "sqlmodel", "pydantic", "sqlalchemy", "typing"]
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3 :: Only",

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/src/sqlmodel_mypy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.18.0"
+__version__ = "0.19.1"
 
 from .persisted import HasId, HasOptionalId, has_id, require_id
 

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/src/sqlmodel_mypy/plugin.py

@@ -163,8 +163,15 @@ SQLMODEL_ASYNC_SESSION_EXECUTE_FULLNAME = "sqlmodel.ext.asyncio.session.AsyncSes
 
 SQLMODEL_SELECT_OF_SCALAR_CLS_FULLNAME = "sqlmodel.sql._expression_select_cls.SelectOfScalar"
 
+# `inspect` is re-exported from `sqlalchemy` and `sqlmodel`.
+SQLALCHEMY_INSPECT_FULLNAMES = {
+    "sqlalchemy.inspect",
+    "sqlalchemy.inspection.inspect",
+    "sqlmodel.inspect",
+}
+
 # Increment when plugin changes should invalidate mypy cache.
-__version__ = 23
+__version__ = 26
 
 
 class _CollectedField(NamedTuple):
@@ -554,6 +561,8 @@ class SQLModelMypyPlugin(Plugin):
             return self._sqlmodel_select_return_type_callback
         if fullname == SQLMODEL_COL_FULLNAME:
             return self._sqlmodel_col_return_type_callback
+        if fullname in SQLALCHEMY_INSPECT_FULLNAMES:
+            return self._sqlalchemy_inspect_return_type_callback
         if fullname in SQLMODEL_TUPLE_FULLNAMES:
             return self._sqlmodel_tuple_return_type_callback
         if fullname == BUILTINS_GETATTR_FULLNAME:
@@ -1751,6 +1760,48 @@ class SQLModelMypyPlugin(Plugin):
 
         return self._sqlalchemy_tuple_expr_type(ctx.api)
 
+    def _sqlalchemy_inspect_return_type_callback(self, ctx: FunctionContext) -> Type:
+        """Type `inspect(Model)` / `inspect(model)` for SQLModel table models.
+
+        SQLAlchemy's overloads for `inspect()` rely on the inspected object implementing typing-only
+        protocols (`_sa_inspect_type` / `_sa_inspect_instance`). SQLModel models are valid ORM entities
+        at runtime, but the required typing surface is not always present for strict type checkers.
+
+        Here we conservatively support the two common ORM introspection patterns:
+        - `inspect(User)` -> `Mapper[User]`
+        - `inspect(user)` -> `InstanceState[User]`
+        """
+        if not ctx.arg_types or not ctx.arg_types[0]:
+            return ctx.default_return_type
+
+        arg0 = get_proper_type(ctx.arg_types[0][0])
+
+        model_inst: Instance | None = None
+        is_type: bool = False
+        if isinstance(arg0, TypeType):
+            item = get_proper_type(arg0.item)
+            if isinstance(item, Instance):
+                model_inst = item
+                is_type = True
+        elif isinstance(arg0, Instance):
+            model_inst = arg0
+            is_type = False
+
+        if model_inst is None:
+            return ctx.default_return_type
+
+        info = model_inst.type
+        if info.fullname == SQLMODEL_BASEMODEL_FULLNAME:
+            return ctx.default_return_type
+        if not info.has_base(SQLMODEL_BASEMODEL_FULLNAME):
+            return ctx.default_return_type
+        if not _is_table_model(info):
+            return ctx.default_return_type
+
+        if is_type:
+            return self._sqlalchemy_mapper_type(ctx.api, model_inst)
+        return self._sqlalchemy_instance_state_type(ctx.api, model_inst)
+
     @staticmethod
     def _lookup_var_in_mro(info: TypeInfo, name: str) -> Var | None:
         """Find a `Var` named `name` in `info` or its MRO (best-effort)."""
@@ -1992,17 +2043,25 @@ class SQLModelMypyPlugin(Plugin):
         if not _is_table_model(info):
             return
 
-        if "__table__" in info.names:
-            return
-
-        table_t = self._sqlalchemy_table_type(ctx.api)
-        v = Var("__table__", table_t)
-        v.info = info
-        v._fullname = f"{info.fullname}.__table__"
-        v.is_classvar = True
-        sym = SymbolTableNode(MDEF, v)
-        sym.plugin_generated = True
-        info.names["__table__"] = sym
+        if "__table__" not in info.names:
+            table_t = self._sqlalchemy_table_type(ctx.api)
+            v = Var("__table__", table_t)
+            v.info = info
+            v._fullname = f"{info.fullname}.__table__"
+            v.is_classvar = True
+            sym = SymbolTableNode(MDEF, v)
+            sym.plugin_generated = True
+            info.names["__table__"] = sym
+
+        if "__mapper__" not in info.names:
+            mapper_t = self._sqlalchemy_mapper_type(ctx.api, fill_typevars(info))
+            v = Var("__mapper__", mapper_t)
+            v.info = info
+            v._fullname = f"{info.fullname}.__mapper__"
+            v.is_classvar = True
+            sym = SymbolTableNode(MDEF, v)
+            sym.plugin_generated = True
+            info.names["__mapper__"] = sym
 
     def _sqlalchemy_table_type(self, api: Any | None = None) -> Type:
         """Return the best available `sqlalchemy` Table-ish type.
@@ -2024,6 +2083,32 @@ class SQLModelMypyPlugin(Plugin):
                 return Instance(info, [])
         return _plugin_any()
 
+    def _sqlalchemy_mapper_type(self, api: Any | None, model_type: Type) -> Type:
+        """Return `sqlalchemy.orm.Mapper[model_type]` (best-effort)."""
+        for fullname in ("sqlalchemy.orm.Mapper", "sqlalchemy.orm.mapper.Mapper"):
+            if api is not None:
+                inst = _named_generic_type_or_none(api, fullname, [model_type])
+                if inst is not None:
+                    return inst
+            info = _lookup_typeinfo(self, fullname)
+            if info is not None:
+                args = [model_type] * len(info.defn.type_vars)
+                return Instance(info, args)
+        return _plugin_any()
+
+    def _sqlalchemy_instance_state_type(self, api: Any | None, model_type: Type) -> Type:
+        """Return `sqlalchemy.orm.InstanceState[model_type]` (best-effort)."""
+        for fullname in ("sqlalchemy.orm.InstanceState", "sqlalchemy.orm.state.InstanceState"):
+            if api is not None:
+                inst = _named_generic_type_or_none(api, fullname, [model_type])
+                if inst is not None:
+                    return inst
+            info = _lookup_typeinfo(self, fullname)
+            if info is not None:
+                args = [model_type] * len(info.defn.type_vars)
+                return Instance(info, args)
+        return _plugin_any()
+
     def _widen_model_config_type(self, ctx: ClassDefContext) -> None:
         mapping_str_any = ctx.api.named_type(
             "typing.Mapping",

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/src/sqlmodel_mypy/transform.py

@@ -1198,11 +1198,25 @@ def add_method(
     """
     info = cls.info
 
-    # Remove previously generated methods.
+    def _remove_stmt(stmt: Statement) -> None:
+        # `list.remove(...)` raises ValueError if not present; ignore.
+        try:
+            cls.defs.body.remove(stmt)
+        except ValueError:
+            return
+
+    # Remove previously generated methods (handle both FuncDef and Decorator nodes).
     if name in info.names:
         sym = info.names[name]
-        if sym.plugin_generated and isinstance(sym.node, FuncDef):
-            cls.defs.body.remove(sym.node)
+        if sym.plugin_generated:
+            node = sym.node
+            if isinstance(node, Decorator):
+                # NOTE: older buggy versions appended the underlying FuncDef instead of the
+                # Decorator; remove both to be safe.
+                _remove_stmt(node)
+                _remove_stmt(node.func)
+            elif isinstance(node, FuncDef):
+                _remove_stmt(node)
 
     # Keep existing definition for semantic analysis by renaming it.
     if name in info.names:
@@ -1248,9 +1262,13 @@ def add_method(
         dec = Decorator(func, [NameExpr("classmethod")], v)
         dec.line = info.line
         sym = SymbolTableNode(MDEF, dec)
+        # NOTE: keep the class body node as a plain FuncDef (this matches the
+        # previous plugin behavior and avoids override-check churn).
+        body_node: Statement = func
     else:
         sym = SymbolTableNode(MDEF, func)
+        body_node = func
 
     sym.plugin_generated = True
     info.names[name] = sym
-    info.defn.defs.body.append(func)
+    info.defn.defs.body.append(body_node)

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/tests/mypy/modules/session_exec.py

@@ -2,9 +2,9 @@ from __future__ import annotations
 
 from typing import Any
 
-from sqlalchemy import text
+from sqlalchemy import select, text
 from sqlalchemy.engine.cursor import CursorResult
-from sqlalchemy.engine.result import Result
+from sqlalchemy.engine.result import Result, TupleResult
 from sqlmodel import Field, Session, SQLModel, create_engine, delete
 from sqlmodel.ext.asyncio.session import AsyncSession
 
@@ -21,6 +21,10 @@ with Session(engine) as session:
     result = session.exec(text("SELECT 1"))
     ok_result: Result[Any] = result
 
+    # accept SQLAlchemy `select(...)` statements (commonly used with SQLModel)
+    select_result = session.exec(select(Hero))
+    _ok_select_result: TupleResult[tuple[Hero]] = select_result
+
     # Keep update/delete statements working (select correct overload).
     delete_result = session.exec(delete(Hero))
     ok_delete_result: CursorResult[Any] = delete_result
@@ -30,5 +34,8 @@ async def async_exec(session: AsyncSession) -> None:
     result2 = await session.exec(text("SELECT 1"))
     _ok_result2: Result[Any] = result2
 
+    select_result2 = await session.exec(select(Hero))
+    _ok_select_result2: TupleResult[tuple[Hero]] = select_result2
+
     delete_result2 = await session.exec(delete(Hero))
     _ok_delete_result2: CursorResult[Any] = delete_result2

sqlmodel_mypy_plugin-0.19.1/tests/mypy/modules/table_dunders.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.orm import InstanceState, Mapper
+from sqlalchemy.sql.schema import Table
+from sqlmodel import Field, SQLModel
+from sqlmodel import inspect as sm_inspect
+
+
+class User(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field()
+
+
+ok_table: Table = User.__table__
+ok_mapper: Mapper[User] = User.__mapper__
+
+# `inspect(...)` should be typed for SQLModel table models (SQLAlchemy + SQLModel re-export).
+ok_mapper2: Mapper[User] = sa_inspect(User)
+ok_mapper3: Mapper[User] = sm_inspect(User)
+
+user = User(name="x")
+ok_state: InstanceState[User] = sa_inspect(user)
+ok_state2: InstanceState[User] = sm_inspect(user)

sqlmodel_mypy_plugin-0.19.1/tests/mypy/outputs/mypy-plugin-strict_ini/session_exec.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import select, text
+from sqlalchemy.engine.cursor import CursorResult
+from sqlalchemy.engine.result import Result, TupleResult
+from sqlmodel import Field, Session, SQLModel, create_engine, delete
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field()
+
+
+engine = create_engine("sqlite://")
+
+with Session(engine) as session:
+    # accept SQLAlchemy (non-SQLModel) Executable statements, e.g. text(...)
+    result = session.exec(text("SELECT 1"))
+    ok_result: Result[Any] = result
+
+    # accept SQLAlchemy `select(...)` statements (commonly used with SQLModel)
+    select_result = session.exec(select(Hero))
+    _ok_select_result: TupleResult[tuple[Hero]] = select_result
+# MYPY: error: Incompatible types in assignment (expression has type "CursorResult[Any]", variable has type "TupleResult[tuple[Hero]]")  [assignment]
+
+    # Keep update/delete statements working (select correct overload).
+    delete_result = session.exec(delete(Hero))
+    ok_delete_result: CursorResult[Any] = delete_result
+
+
+async def async_exec(session: AsyncSession) -> None:
+    result2 = await session.exec(text("SELECT 1"))
+    _ok_result2: Result[Any] = result2
+
+    select_result2 = await session.exec(select(Hero))
+    _ok_select_result2: TupleResult[tuple[Hero]] = select_result2
+# MYPY: error: Incompatible types in assignment (expression has type "CursorResult[Any]", variable has type "TupleResult[tuple[Hero]]")  [assignment]
+
+    delete_result2 = await session.exec(delete(Hero))
+    _ok_delete_result2: CursorResult[Any] = delete_result2

sqlmodel_mypy_plugin-0.19.1/tests/mypy/outputs/mypy-plugin_ini/session_exec.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import select, text
+from sqlalchemy.engine.cursor import CursorResult
+from sqlalchemy.engine.result import Result, TupleResult
+from sqlmodel import Field, Session, SQLModel, create_engine, delete
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+
+class Hero(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field()
+
+
+engine = create_engine("sqlite://")
+
+with Session(engine) as session:
+    # accept SQLAlchemy (non-SQLModel) Executable statements, e.g. text(...)
+    result = session.exec(text("SELECT 1"))
+    ok_result: Result[Any] = result
+
+    # accept SQLAlchemy `select(...)` statements (commonly used with SQLModel)
+    select_result = session.exec(select(Hero))
+    _ok_select_result: TupleResult[tuple[Hero]] = select_result
+# MYPY: error: Incompatible types in assignment (expression has type "CursorResult[Any]", variable has type "TupleResult[tuple[Hero]]")  [assignment]
+
+    # Keep update/delete statements working (select correct overload).
+    delete_result = session.exec(delete(Hero))
+    ok_delete_result: CursorResult[Any] = delete_result
+
+
+async def async_exec(session: AsyncSession) -> None:
+    result2 = await session.exec(text("SELECT 1"))
+    _ok_result2: Result[Any] = result2
+
+    select_result2 = await session.exec(select(Hero))
+    _ok_select_result2: TupleResult[tuple[Hero]] = select_result2
+# MYPY: error: Incompatible types in assignment (expression has type "CursorResult[Any]", variable has type "TupleResult[tuple[Hero]]")  [assignment]
+
+    delete_result2 = await session.exec(delete(Hero))
+    _ok_delete_result2: CursorResult[Any] = delete_result2

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/tests/test_plugin_unit.py

@@ -2941,3 +2941,28 @@ def test_select_signature_hook_is_idempotent_for_star_overload() -> None:
         hook(FunctionSigContext(args=[], default_signature=default_sig, context=call, api=api))
         is default_sig
     )
+
+
+def test_sqlalchemy_typing_helpers_fallback_to_any(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Cover SQLAlchemy typing helper fallbacks (best-effort robustness)."""
+    p = plugin_mod.SQLModelMypyPlugin(Options())
+    any_t = AnyType(TypeOfAny.explicit)
+
+    def _no_lookup(_plugin: object, _fullname: str) -> None:
+        return None
+
+    monkeypatch.setattr(plugin_mod, "_lookup_typeinfo", _no_lookup)
+
+    assert isinstance(get_proper_type(p._sqlalchemy_table_type(None)), AnyType)
+    assert isinstance(get_proper_type(p._sqlalchemy_mapper_type(None, any_t)), AnyType)
+    assert isinstance(get_proper_type(p._sqlalchemy_instance_state_type(None, any_t)), AnyType)
+
+
+def test_sqlalchemy_instance_state_type_uses_named_generic_type() -> None:
+    """Cover the fast-path branch for InstanceState typing."""
+    p = plugin_mod.SQLModelMypyPlugin(Options())
+    api = DummyCheckerAPI()
+    any_t = AnyType(TypeOfAny.explicit)
+
+    out = p._sqlalchemy_instance_state_type(api, any_t)
+    assert isinstance(get_proper_type(out), Instance)

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.1}/tests/test_transform_unit.py

@@ -657,7 +657,58 @@ def test_add_method_generates_and_replaces_methods() -> None:
         api, cls, "cm", args=[arg], return_type=AnyType(TypeOfAny.explicit), is_classmethod=True
     )
     assert "cm" in cls.info.names
-    assert isinstance(cls.info.names["cm"].node, Decorator)
+    cm_node = cls.info.names["cm"].node
+    assert isinstance(cm_node, Decorator)
+    assert cm_node.func.is_class is True
+    assert cm_node not in cls.defs.body
+    assert cm_node.func in cls.defs.body
+
+
+def test_add_method_classmethod_reentry_is_idempotent_and_handles_legacy_body() -> None:
+    api = DummyAPI()
+    cls = make_sqlmodel_class()
+
+    any_t = AnyType(TypeOfAny.explicit)
+    arg = Argument(Var("x", any_t), any_t, None, ARG_NAMED)
+
+    # First generation
+    add_method(
+        api, cls, "cm", args=[arg], return_type=AnyType(TypeOfAny.explicit), is_classmethod=True
+    )
+    node1 = cls.info.names["cm"].node
+    assert isinstance(node1, Decorator)
+    assert node1 not in cls.defs.body
+    assert node1.func in cls.defs.body
+    assert node1.func.is_class is True
+
+    # Re-entry: previously generated Decorator should be removed, no duplicates.
+    add_method(
+        api, cls, "cm", args=[arg], return_type=AnyType(TypeOfAny.explicit), is_classmethod=True
+    )
+    node2 = cls.info.names["cm"].node
+    assert isinstance(node2, Decorator)
+    assert node2 not in cls.defs.body
+    assert node2.func in cls.defs.body
+    assert node1.func not in cls.defs.body
+    assert node2.func.is_class is True
+    assert sum(1 for s in cls.defs.body if isinstance(s, FuncDef) and s.name == "cm") == 1
+
+    # Simulate legacy buggy state: body contains both Decorator and FuncDef.
+    cls.defs.body.append(node2)
+    assert node2 in cls.defs.body
+    assert node2.func in cls.defs.body
+
+    add_method(
+        api, cls, "cm", args=[arg], return_type=AnyType(TypeOfAny.explicit), is_classmethod=True
+    )
+    node3 = cls.info.names["cm"].node
+    assert isinstance(node3, Decorator)
+    assert node3 not in cls.defs.body
+    assert node3.func in cls.defs.body
+    assert node2 not in cls.defs.body
+    assert node2.func not in cls.defs.body
+    assert node3.func.is_class is True
+    assert sum(1 for s in cls.defs.body if isinstance(s, FuncDef) and s.name == "cm") == 1
 
 
 def test_transform_defer_paths() -> None: