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

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

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

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.0}/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.0}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: sqlmodel-mypy-plugin
-Version: 0.18.0
+Version: 0.19.0
 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

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

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlmodel-mypy-plugin"
-version = "0.18.0"
+version = "0.19.0"
 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.0}/src/sqlmodel_mypy/__init__.py

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

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.0}/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__ = 25
 
 
 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:
@@ -1266,6 +1275,34 @@ class SQLModelMypyPlugin(Plugin):
                 return any(_contains_instance_fullname(item, fullname) for item in proper.items)
             return False
 
+        # Accept SQLAlchemy `Select[...]` in `Session.exec(...)`.
+        #
+        # SQLModel defines its own `Select[...]` wrapper class and types `Session.exec` to accept it,
+        # but users often import and use SQLAlchemy's `select()` directly. Runtime supports it, and
+        # with this adjustment we preserve a correctly-shaped `TupleResult[...]` return type.
+        sqlmodel_select_info = _lookup_typeinfo(self, SQLMODEL_SELECT_CLS_FULLNAME)
+        sqlalchemy_select_info = _lookup_typeinfo(self, SQLALCHEMY_SELECT_FULLNAME)
+        if sqlmodel_select_info is not None and sqlalchemy_select_info is not None:
+            if _contains_instance_fullname(default.arg_types[0], sqlmodel_select_info.fullname):
+                # Idempotency: if upstream stubs already accept SQLAlchemy Select, keep unchanged.
+                if not _contains_instance_fullname(
+                    default.arg_types[0], sqlalchemy_select_info.fullname
+                ):
+                    proper_arg0 = get_proper_type(default.arg_types[0])
+                    if isinstance(proper_arg0, Instance) and proper_arg0.args:
+                        row_type = proper_arg0.args[0]
+                    else:
+                        row_type = _plugin_any()
+                    sqlalchemy_select = Instance(
+                        sqlalchemy_select_info,
+                        [row_type] * len(sqlalchemy_select_info.defn.type_vars),
+                    )
+                    new_arg_types = list(default.arg_types)
+                    new_arg_types[0] = UnionType.make_union(
+                        [default.arg_types[0], sqlalchemy_select]
+                    )
+                    return default.copy_modified(arg_types=new_arg_types)
+
         # Only adjust the broad overload; keep Select/SelectOfScalar overloads precise.
         broad = False
         if sqlmodel_executable_info is not None and _contains_instance_fullname(
@@ -1751,6 +1788,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 +2071,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 +2111,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.0}/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.0/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.18.0 → sqlmodel_mypy_plugin-0.19.0}/tests/mypy/outputs/mypy-plugin-strict_ini/aliased_joins.py

@@ -28,6 +28,5 @@ with Session(engine) as session:
         ok_team: Team | None = team
 
         bad_team: Team = team
-# MYPY: error: Incompatible types in assignment (expression has type "Team | None", variable has type "Team")  [assignment]
         if team is not None:
             ok_team_name: str = team.name

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.0}/tests/mypy/outputs/mypy-plugin-strict_ini/docs_parity_read_connected_data.py

@@ -37,6 +37,7 @@ with Session(engine) as session:
     stmt_heroes_only = select(Hero).join(Team).where(Team.name == "Preventers")
     for hero3 in session.exec(stmt_heroes_only):
         ok_hero3: Hero = hero3
+# MYPY: error: Incompatible types in assignment (expression has type "tuple[Hero]", variable has type "Hero")  [assignment]
 
     # Docs pattern: LEFT OUTER join via isouter=True.
     stmt_outer = select(Hero, Team).join(Team, isouter=True)
@@ -46,4 +47,3 @@ with Session(engine) as session:
 
         # Outer join may yield `None` for the right-hand entity.
         bad_team4: Team = team4
-# MYPY: error: Incompatible types in assignment (expression has type "Team | None", variable has type "Team")  [assignment]

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.0}/tests/mypy/outputs/mypy-plugin-strict_ini/execution_options.py

@@ -30,4 +30,3 @@ with Session(engine) as session:
 
         # Outer join may yield `None` for the right-hand entity.
         bad_team: Team = team
-# MYPY: error: Incompatible types in assignment (expression has type "Team | None", variable has type "Team")  [assignment]

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.0}/tests/mypy/outputs/mypy-plugin-strict_ini/joins.py

@@ -32,7 +32,6 @@ with Session(engine) as session:
 
         # Outer join may yield `None` for the right-hand entity.
         bad_team: Team = team2
-# MYPY: error: Incompatible types in assignment (expression has type "Team | None", variable has type "Team")  [assignment]
         if team2 is not None:
             ok_team_name2: str = team2.name
 
@@ -42,7 +41,6 @@ with Session(engine) as session:
         ok_hero3: Hero = hero3
         ok_team3: Team | None = team3
         bad_team3: Team = team3
-# MYPY: error: Incompatible types in assignment (expression has type "Team | None", variable has type "Team")  [assignment]
 
     # One-to-many join via relationship attribute target should also propagate `None`.
     stmt_outer_rel_many = select(Team, Hero).join(Team.heroes, isouter=True)
@@ -50,6 +48,5 @@ with Session(engine) as session:
         ok_team4: Team = team4
         ok_hero4: Hero | None = hero4
         bad_hero4: Hero = hero4
-# MYPY: error: Incompatible types in assignment (expression has type "Hero | None", variable has type "Hero")  [assignment]
         if hero4 is not None:
             ok_hero4_name: str = hero4.name

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.0}/tests/mypy/outputs/mypy-plugin_ini/aliased_joins.py

@@ -28,6 +28,5 @@ with Session(engine) as session:
         ok_team: Team | None = team
 
         bad_team: Team = team
-# MYPY: error: Incompatible types in assignment (expression has type "Team | None", variable has type "Team")  [assignment]
         if team is not None:
             ok_team_name: str = team.name

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.0}/tests/mypy/outputs/mypy-plugin_ini/execution_options.py

@@ -30,4 +30,3 @@ with Session(engine) as session:
 
         # Outer join may yield `None` for the right-hand entity.
         bad_team: Team = team
-# MYPY: error: Incompatible types in assignment (expression has type "Team | None", variable has type "Team")  [assignment]

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.0}/tests/mypy/outputs/mypy-plugin_ini/joins.py

@@ -32,7 +32,6 @@ with Session(engine) as session:
 
         # Outer join may yield `None` for the right-hand entity.
         bad_team: Team = team2
-# MYPY: error: Incompatible types in assignment (expression has type "Team | None", variable has type "Team")  [assignment]
         if team2 is not None:
             ok_team_name2: str = team2.name
 
@@ -42,7 +41,6 @@ with Session(engine) as session:
         ok_hero3: Hero = hero3
         ok_team3: Team | None = team3
         bad_team3: Team = team3
-# MYPY: error: Incompatible types in assignment (expression has type "Team | None", variable has type "Team")  [assignment]
 
     # One-to-many join via relationship attribute target should also propagate `None`.
     stmt_outer_rel_many = select(Team, Hero).join(Team.heroes, isouter=True)
@@ -50,6 +48,5 @@ with Session(engine) as session:
         ok_team4: Team = team4
         ok_hero4: Hero | None = hero4
         bad_hero4: Hero = hero4
-# MYPY: error: Incompatible types in assignment (expression has type "Hero | None", variable has type "Hero")  [assignment]
         if hero4 is not None:
             ok_hero4_name: str = hero4.name

{sqlmodel_mypy_plugin-0.18.0 → sqlmodel_mypy_plugin-0.19.0}/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/ROADMAP.md

@@ -1,349 +0,0 @@
-# Roadmap
-
-## v0.1 (MVP) - DONE
-
-- Correct required/optional kwargs for `sqlmodel.Field(...)` when generating `__init__`.
-- Exclude `sqlmodel.Relationship(...)` from generated `__init__` kwargs.
-- Minimal plugin config + cache invalidation via `report_config_data()`.
-- Mypy integration test suite with golden outputs.
-
-## v0.2 - DONE
-
-- Config parity with Pydantic plugin (more knobs; documented):
-  - `init_typed`
-  - `init_forbid_extra`
-- Better handling of inherited fields (including generics/typevars) and overrides.
-
-## v0.3 - DONE
-
-- Relationship typing improvements (forward refs, `Mapped[...]` wrapping behavior).
-- Typed SQL expression building (reduce need for `col()`, `table.c.*`, etc.):
-  - Improve class/instance attribute typing so `User.id`, `User.name`, etc. are well-typed in expressions.
-  - Ensure common SQLModel re-exports (`select`, `and_`, `or_`, `col`, etc.) preserve SQLAlchemy typing.
-  - Decide approach: plugin hooks vs stub overlays vs relying on SQLAlchemy typing (documented trade-offs).
-- Compatibility matrix CI across mypy/SQLModel versions (and pin policy).
-- **Plugin ordering guardrails (mypy limitation)**
-  - **Reality check**: mypy generally uses the **first plugin that claims a hook**, so true "order independence"
-    between `sqlmodel_mypy.plugin` and `pydantic.mypy` is not realistically achievable today.
-  - Enforce and clearly explain that `sqlmodel_mypy.plugin` must be listed **before** `pydantic.mypy`:
-    - Source: `src/sqlmodel_mypy/plugin.py` (`SQLModelMypyPlugin.__init__`, `_sqlmodel_metaclass_callback()`).
-    - User-facing docs: `README.md` (plugin ordering section).
-
-## v0.4 (Docs-aligned relationship constructors) - DONE
-
-**Motivation**: SQLModel's official docs pass relationship attributes in constructors (e.g. `Hero(team=team)`,
-`Team(heroes=[...])`). v0.4 accepts relationship kwargs in generated `__init__` / `model_construct` for
-`table=True` models, so `init_forbid_extra=true` no longer causes false-positive "unexpected keyword argument"
-errors for documented patterns.
-
-- **Accept relationship kwargs in generated `__init__` / `model_construct` (table models)**
-  - Allow many-to-one and one-to-many patterns from the docs:
-    - `Hero(..., team=team_obj)` / `hero.team = team_obj`
-    - `Team(..., heroes=[hero1, hero2])` / `team.heroes.append(hero)`
-    - Docs: `https://sqlmodel.tiangolo.com/tutorial/relationship-attributes/create-and-update-relationships/`
-  - Allow many-to-many relationship kwargs (lists) from the docs:
-    - `Hero(..., teams=[team1, team2])` with `link_model=...`
-    - Docs: `https://sqlmodel.tiangolo.com/tutorial/many-to-many/create-data/`
-  - Keep behavior **scoped to `table=True` models** (relationship kwargs are applied after construction in SQLModel):
-    - Source: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/_compat.py` (`sqlmodel_table_construct()`,
-      `sqlmodel_validate()` assign relationship keys after fields).
-  - Add/extend mypy integration tests covering relationship kwargs under both configs:
-    - `init_forbid_extra=false` and `init_forbid_extra=true`
-    - `init_typed=false` and `init_typed=true`
-
-- **Join/outer-join query typing coverage (SQLModel docs patterns)**
-  - Ensure expression typing works for doc examples using joins:
-    - `select(Hero, Team).join(Team)` and `select(Hero, Team).join(Team, isouter=True)`
-    - Docs: `https://sqlmodel.tiangolo.com/tutorial/connect/read-connected-data/`
-
-## v0.4.1 (Outer-join `None` propagation) - DONE
-
-- Decide how to model **outer-join `None` propagation** in result tuples (docs show `Team: None`):
-  - Either type `Team | None` on the right-hand side when `isouter=True`, or document a recommended narrowing
-    pattern (and keep types conservative).
-  - Update/add mypy integration tests to match the chosen strategy.
-
-## v0.5 (Model-kind awareness + reduce "surprising" typing) - DONE
-
-- **Table-model awareness for SQLAlchemy expression typing**
-  - Only treat class attributes as SQLAlchemy expressions (e.g. wrap to `InstrumentedAttribute[T]`) for `table=True`
-    SQLModel models.
-  - Avoid changing attribute types for "data models" (non-table SQLModel subclasses) used for FastAPI schemas, e.g.
-    `TeamBase`, `HeroCreate`, `HeroPublic`.
-    - Docs: `https://sqlmodel.tiangolo.com/tutorial/fastapi/relationships/`
-
-- **Pydantic/Field alias & config parity checkpoints**
-  - Verify our generated signatures stay compatible with SQLModel's `Field(...)` alias behavior (alias propagation
-    and precedence in `validation_alias` / `serialization_alias`).
-    - Source: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/main.py` (`Field()` implementation).
-  - Document what is supported vs intentionally out of scope when users rely on aliases in constructor kwargs.
-
-## v0.6 (Session.exec / AsyncSession.exec typing gaps) - DONE
-
-- **Broaden `Session.exec()` / `AsyncSession.exec()` accepted statement types**
-  - Fix common mypy failures when passing non-`Select` statements (e.g. `delete(...)`) to `exec()`.
-  - Implement via upstream PRs and/or stub overlays (keep runtime behavior unchanged):
-    - Source: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/orm/session.py`
-    - Source: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/ext/asyncio/session.py`
-    - Known gap example: `https://github.com/fastapi/sqlmodel/discussions/831`
-
-## v0.7 (Advanced SQL expression + relationship comparator typing) - DONE
-
-- **Relationship comparator typing**
-  - `.any()`, `.has()`, `.contains()`, etc. on relationship attributes in query expressions.
-- **More query-shape coverage**
-  - Multi-entity selects, joins/outer-joins, and relationship-based filters across common SQLModel tutorial patterns.
-- **Document trade-offs (and pick a default strategy)**
-  - Plugin hooks vs stub overlays vs relying purely on SQLAlchemy typing (with "when to use what" guidance).
-
-## v0.8 (Field `sa_type=` supports SQLAlchemy TypeEngine instances) - DONE
-
-**Motivation**: SQLModel's `Field(sa_type=...)` is a supported API, but real-world usage commonly passes
-**instantiated SQLAlchemy types** (e.g. `DateTime(timezone=True)`, `String(50)`), which triggers mypy
-`call-overload` errors under `--strict`. Users currently work around this with `sa_column=Column(...)` or
-`# type: ignore`, which is exactly the "types clutter" we want to remove.
-
-- **Fix mypy `call-overload` for `Field(sa_type=<TypeEngine instance>)`**
-  - Upstream issue reports:
-    - `https://github.com/fastapi/sqlmodel/discussions/955`
-    - `https://github.com/fastapi/sqlmodel/discussions/1228`
-  - Upstream pending fix (adjust `sa_type` annotation to match SQLAlchemy's `Column` type argument rules):
-    - `https://github.com/fastapi/sqlmodel/pull/1345`
-  - Source references:
-    - SQLModel `Field()` signature: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/main.py`
-    - SQLAlchemy `Column` accepts both a **TypeEngine class** and a **TypeEngine instance** (see PR #1345 write-up).
-
-- **Implementation options (pick default; document trade-offs)**
-  - **Preferred**: upstream-first — rely on SQLModel merging PR #1345; in our plugin add a compatibility layer for
-    older SQLModel releases and/or for users stuck on versions without the fix.
-  - **Plugin signature hook**: add a `Field()` signature hook that widens `sa_type` to accept
-    `sqlalchemy.sql.type_api.TypeEngine[Any] | type[Any]` when present.
-  - **Stub overlay**: ship a small `.pyi` overlay (or `typing`-only shim) to widen the `Field()` overload(s) without
-    touching runtime behavior.
-
-- **Tests**
-  - Add a mypy integration module that reproduces the failure in strict mode and asserts it's fixed without
-    `# type: ignore`, e.g.:
-    - `Field(sa_type=DateTime(timezone=True))`
-    - `Field(sa_type=String(50))`
-  - Ensure the fix is **idempotent**: if upstream SQLModel already accepts instances, our hook/overlay must not
-    change behavior or introduce new ambiguities.
-
-## v0.9 (`model_config = ConfigDict(...)` compatibility in strict mode) - DONE
-
-**Motivation**: SQLModel is built on Pydantic v2, and users often want to set things like `extra="forbid"` on
-schema-like models (e.g. `HeroCreate`, `HeroUpdate`) via `model_config = ConfigDict(...)`. Today this can fail mypy
-strict with an "incompatible types in assignment" error (`ConfigDict` vs `SQLModelConfig`), forcing users into
-`# type: ignore` or `cast(...)`.
-
-- **Fix mypy incompatibility for `model_config` overrides**
-  - Upstream discussion / reproduction:
-    - `https://github.com/fastapi/sqlmodel/discussions/855`
-  - Source references:
-    - SQLModel config typing helpers: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/_compat.py`
-    - SQLModel base class `model_config` annotation: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/main.py`
-
-- **Implementation options (pick default; document trade-offs)**
-  - **Stub overlay (likely simplest)**: type `SQLModel.model_config` as `pydantic.ConfigDict` (or `Mapping[str, Any]`)
-    so assignment from `ConfigDict(...)` is always accepted.
-  - **Plugin adjustment**: during semantic analysis, rewrite the inferred type of `model_config` on SQLModel subclasses
-    to a compatible supertype (while keeping runtime untouched).
-  - Ensure we don't regress table-model behavior: SQLModel uses `model_config["table"]` and `model_config["registry"]`
-    at runtime (see `SQLModelMetaclass.__new__`).
-
-- **Tests**
-  - Add a mypy integration module proving strict-mode acceptance without ignores, e.g.:
-    - `from pydantic import ConfigDict`
-    - `class HeroCreate(SQLModel): model_config = ConfigDict(extra="forbid")`
-  - Include a minimal table model + data model inheritance case (common in SQLModel docs) to ensure no false positives.
-
-## v0.10 (`select()` varargs: avoid overload ceiling) - DONE
-
-**Motivation**: SQLModel provides its own typed `select()` overloads, but they are generated only up to **4**
-entities. In real code it's common to select more than 4 columns/entities (especially with joins/aggregates), which
-can trigger "No overload variant of `select` matches argument types …" even though runtime works.
-
-- **Fix overload ceiling for `sqlmodel.select(...)`**
-  - Source reference (generated overloads; note the 4-entity cap):
-    - `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/sql/_expression_select_gen.py`
-  - Upstream issue reports:
-    - `https://github.com/fastapi/sqlmodel/issues/92`
-    - `https://github.com/fastapi/sqlmodel/issues/271`
-
-- **Implementation options (pick default; document trade-offs)**
-  - **Stub overlay (likely simplest)**: add a final "varargs fallback" overload, e.g.:
-    - `@overload`
-    - `def select(__ent0: Any, __ent1: Any, __ent2: Any, __ent3: Any, __ent4: Any, *entities: Any) -> Select[tuple[Any, ...]]: ...`
-    so mypy always has a matching overload beyond 4 args.
-  - **Plugin signature hook**: provide a mypy hook for `sqlmodel.sql.expression.select` that adds the same fallback
-    overload, keeping the existing 1–4 entity overload precision.
-  - Optionally, generate more precise overloads (e.g. up to 8) if we're willing to carry the maintenance cost.
-
-- **Tests**
-  - Add a mypy integration module that selects 5+ entities and asserts no `call-overload` errors under strict mode.
-  - Decide and lock down the fallback return type (likely `Select[tuple[Any, ...]]`) to keep behavior predictable.
-
-## v0.11 (SQLAlchemy "extras" coverage + SQLModel `Select` join parity) - DONE
-
-- **Lock down common SQLAlchemy helpers used with SQLModel**
-  - `.label(...)` on `table=True` model fields typed as SQLAlchemy expressions.
-  - ORM loader options like `selectinload(Model.relationship)` on `table=True` relationships.
-  - `Select.execution_options(...)` chaining without losing the `Select[...]` generic (including outer-join `None` propagation).
-- **Fix outer-join `None` propagation for SQLModel's own `Select` wrapper**
-  - Apply the join/outerjoin return-type adjustment to both SQLAlchemy `Select` and SQLModel's `sqlmodel.sql._expression_select_cls.Select`.
-- **Tests**
-  - Add/extend mypy integration coverage and commit golden outputs for the new cases.
-
-## v0.12 (`__table__` dunder typing + `Session.get`/`AsyncSession.get` coverage) - DONE
-
-**Motivation**: SQLAlchemy APIs and patterns commonly rely on ORM models exposing `Model.__table__`. SQLModel
-models do provide this at runtime for `table=True`, but type checkers can miss it and report `attr-defined`.
-
-- **Expose and type `__table__` on `table=True` SQLModel models**
-  - Provide a plugin-generated `__table__` attribute typed as `sqlalchemy.sql.schema.Table` (with safe fallbacks
-    when stubs don't expose `Table`).
-- **Tests**
-  - Add mypy integration coverage for `Model.__table__` and `Session.get` / `AsyncSession.get` with SQLModel
-    table models.
-
-## v0.12.4 (Dynamic query-builder helpers) - DONE
-
-- Type `getattr(Model, "field")` like `Model.field` for `table=True` SQLModel models (string-literal names only).
-- Best-effort typing for `column_property(...)` return type (infer `Mapped[T]`) to support
-  `Model._foo = column_property(...)` patterns.
-
-## v0.14 (`typing.Annotated[...]` field metadata support) - DONE
-
-**Motivation**: SQLModel (Pydantic v2) supports `Annotated`-driven typing patterns, and users will naturally try to
-use them to reduce `= Field(...)` assignment noise. Under `--strict`, we should still generate correct constructor
-signatures (required/optional + alias kwargs) when `Field(...)` metadata lives inside `Annotated[...]`.
-
-- **Support `Annotated[T, Field(...)]` for constructor/signature generation**
-  - Examples we should handle (at least best-effort):
-    - `id: Annotated[int | None, Field(default=None, primary_key=True)]`
-    - `name: Annotated[str, Field(alias="full_name")]`
-    - The historical SQLModel edge-case: `Optional[Annotated[T, ...]]` (see upstream release notes).
-  - Implementation sketch:
-    - Extend semantic-phase collection in `src/sqlmodel_mypy/transform.py` to extract Field metadata from the
-      annotation when there is no `= Field(...)` call in the class body.
-    - Mirror the same logic in checker-time signature collection in `src/sqlmodel_mypy/plugin.py`
-      (`_collect_member_from_stmt`) so class-call signatures stay consistent with generated `__init__`.
-  - Source references:
-    - SQLModel `Field()` overloads + alias precedence: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/main.py`
-    - `Annotated` handling in SQLModel's type parsing: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/_compat.py`
-    - Release note: "Fix support for types with `Optional[Annotated[x, f()]]`…" (PR #1093):
-      `https://github.com/fastapi/sqlmodel/pull/1093`
-
-## v0.15 (Outer-join `None` propagation for relationship-attribute joins) - DONE
-
-**Motivation**: we currently propagate `None` on outer-joins only when the join target is a direct model class
-(e.g. `.join(Team, isouter=True)`). A common ORM pattern is to join via relationship attributes
-(e.g. `.join(Hero.team, isouter=True)`), and the result tuple should still reflect that the joined entity may be
-`None`.
-
-- **Expand join-target detection**
-  - Extend `src/sqlmodel_mypy/plugin.py` (`_sqlalchemy_select_join_like_return_type`) to also detect join targets
-    expressed as relationship attributes (e.g. `Hero.team`, `Team.heroes`) and map them to the target model type
-    for `None` propagation.
-  - References:
-    - SQLModel outer-join behavior (baseline example): `https://sqlmodel.tiangolo.com/tutorial/connect/read-connected-data/`
-    - SQLAlchemy relationship-attribute joins (`select(User).join(User.addresses)`): `https://docs.sqlalchemy.org/en/20/orm/queryguide/select.html#simple-relationship-joins`
-  - Add mypy integration coverage under `tests/mypy/modules/` for relationship-attribute joins, including the SQLModel
-    docs pattern of `Team: None` on outer-joins.
-
-## v0.16 (Strict typing ergonomics add-ons, opt-in) - DONE
-
-**Motivation**: strict typing + SQLModel often means the database populates values "later" (after flush/commit/
-refresh), especially primary keys (`id: int | None`). Mypy can't infer those runtime effects, and users end up with
-repeated `assert obj.id is not None` (type clutter).
-
-- **Provide a tiny opt-in narrowing helper**
-  - Docs context (why `id` starts as `None` and is populated after commit/refresh):
-    - `https://sqlmodel.tiangolo.com/tutorial/automatic-id-none-refresh/`
-  - Ship a small helper in this package (runtime-free or near-zero runtime) that helps users narrow "persisted" models
-    without `cast(...)`/`# type: ignore`, e.g.:
-    - `assert_persisted(obj)` / `require_id(obj)` / `ensure_persisted(obj)` returning a `TypeGuard[...]` or using
-      overloads to narrow `id` to `int`.
-  - Keep it optional and well-documented; default plugin behavior should remain conservative.
-
-## v0.17 (`tuple_()` should return a SQL expression, not a Python tuple) - DONE
-
-**Motivation**: SQLModel re-exports `tuple_` from `sqlmodel.sql.expression`, but its typing currently says it returns a
-built-in `tuple[Any, ...]`. In SQLAlchemy, `tuple_()` returns a SQL expression object (`sqlalchemy.sql.elements.Tuple`)
-which supports expression methods like `.in_(...)`. Under `--strict` this mismatch forces `cast(...)` / `# type: ignore`
-for otherwise normal SQLAlchemy patterns.
-
-- **Fix `sqlmodel.tuple_` / `sqlmodel.sql.expression.tuple_` return type**
-  - Add a plugin return-type hook for:
-    - `sqlmodel.sql.expression.tuple_`
-    - `sqlmodel.tuple_` (re-export)
-  - Prefer returning `sqlalchemy.sql.elements.Tuple` (or fall back to `ColumnElement[tuple[Any, ...]]` if stubs vary).
-  - Source references:
-    - SQLModel wrapper: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/sql/expression.py`
-    - SQLAlchemy `tuple_` constructor: `https://github.com/sqlalchemy/sqlalchemy/blob/main/lib/sqlalchemy/sql/_elements_constructors.py`
-    - SQLAlchemy `Tuple` expression class: `https://github.com/sqlalchemy/sqlalchemy/blob/main/lib/sqlalchemy/sql/elements.py`
-- **Tests**
-  - Add a mypy integration module demonstrating composite IN typing without ignores, e.g.:
-    - `tuple_(User.id, User.team_id).in_([(1, 2)])`
-
-## v0.18 (Comprehensive typing polish) - DONE
-
-This release consolidates several enhancements to round out SQLModel/mypy strict-mode ergonomics.
-
-### Recognize `table=True` via `model_config["table"]`
-
-SQLModel's runtime `is_table_model_class()` checks `model_config.get("table")`, so a class can be a table model even
-without `class Model(SQLModel, table=True)`.
-
-- Extend semantic analysis in `src/sqlmodel_mypy/transform.py` to detect `model_config = ConfigDict(table=True)`.
-- Persist the result in `TypeInfo.metadata["sqlmodel-mypy-metadata"]`, then update `_is_table_model(...)` in both
-  `plugin.py` and `transform.py` to consult metadata first.
-- Source references:
-  - SQLModel metaclass: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/main.py` (`SQLModelMetaclass.__new__`)
-  - SQLModel runtime table detection: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/_compat.py`
-
-### `select(5+)`: recover tuple element types
-
-v0.10 fixed the overload ceiling by accepting `select(5+)`, but the fallback return type was `Select[tuple[Any, ...]]`.
-
-- Add a best-effort return-type hook that recovers element types from inferred argument expression types.
-- Code: `_sqlmodel_select_signature_callback()`, `_sqlmodel_select_return_type_callback()`, `_sqlmodel_select_entity_result_type()`
-- Tests: `tests/mypy/modules/select_varargs.py`
-
-### Outer-join `None` propagation for aliased/variable join targets
-
-Outer-join `None` propagation previously only worked when the join target was a direct model ref or relationship
-attribute, not when users join via an alias variable (e.g. `team_alias = aliased(Team)`).
-
-- Extend join target type inference to handle typed variables (including `aliased(Model)` results).
-- Code: `_typeinfo_from_join_target_expr()`, `_typeinfo_from_typed_join_target_expr()`, `_typeinfo_from_typed_join_target_type()`
-- Tests: `tests/mypy/modules/aliased_joins.py`
-
-### `getattr(Model, NAME)`: support `Final`/`Literal[...]` names
-
-Dynamic query builders often use constants for attribute names; without this, `getattr(...)` falls back to `Any`.
-
-- Extend `getattr(Model, NAME)` typing beyond string literals by accepting name args typed as string `Literal[...]`
-  (and best-effort `Final` constants where mypy retains the literal).
-- Code: `_sqlmodel_getattr_return_type_callback()`
-- Tests: `tests/mypy/modules/getattr_column_property.py`
-
-### `Field(validation_alias=...)`: Pydantic v2 alias parity
-
-Pydantic v2 supports `validation_alias=AliasPath(...)` / `AliasChoices(...)`, but SQLModel's `Field(...)` typing is
-narrower; strict mypy users otherwise need `cast(...)`/`# type: ignore`.
-
-- Widen `Field(validation_alias=...)` to accept `pydantic.aliases.AliasPath | AliasChoices` (idempotent if upstream
-  is already widened).
-- Code: `_sqlmodel_field_signature_callback()`
-- Tests: `tests/mypy/modules/field_validation_alias.py`
-
-### Optional typed `Session.execute()` / `AsyncSession.execute()`
-
-SQLModel overrides `execute()` and types it as `Result[Any]`, shadowing SQLAlchemy's typed overloads. Even though
-`execute()` is deprecated in SQLModel docs, users still rely on it during migrations.
-
-- Add an opt-in mypy plugin behavior that types `execute(select(...))` as `Result[...]` (and preserves async wrapping).
-- Config: `typed_execute = true` under `[sqlmodel-mypy]`
-- Code: `SQLModelPluginConfig.typed_execute`, `_sqlmodel_session_execute_return_type_callback()`, `_row_tuple_type_from_typed_statement()`
-- Tests: `tests/mypy/configs/mypy-plugin-strict-typed-execute.ini`, `tests/mypy/modules/session_execute_typed.py`

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

@@ -1,12 +0,0 @@
-from __future__ import annotations
-
-from sqlalchemy.sql.schema import Table
-from sqlmodel import Field, SQLModel
-
-
-class User(SQLModel, table=True):
-    id: int | None = Field(default=None, primary_key=True)
-    name: str = Field()
-
-
-ok_table: Table = User.__table__