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

{sqlmodel_mypy_plugin-0.12.3 → sqlmodel_mypy_plugin-0.18.0}/AGENTS.md

@@ -47,8 +47,11 @@ make update-mypy
 ## What the plugin does (scope)
 
 - Collects SQLModel fields and determines required/optional kwargs based on `sqlmodel.Field(...)`.
-- **Ignores** `sqlmodel.Relationship(...)` when generating constructor kwargs.
+- For `table=True` models, includes `sqlmodel.Relationship(...)` members as **optional** constructor kwargs.
 - Synthesizes `__init__` and `model_construct` signatures for SQLModel subclasses during mypy semantic analysis.
+- Adjusts `table=True` SQLModel class attribute types to behave like SQLAlchemy expressions (e.g. `User.id` and relationship expression/comparator patterns).
+- Exposes SQLAlchemy table metadata on `table=True` models (e.g. `Model.__table__`).
+- Adds targeted typing fixes for common query patterns/helpers (`select(...)` 5+ entities fallback, `sqlmodel.tuple_(...)` as an expression, outer-join `None` propagation, broadened `Session.exec(...)`, optional typed `Session.execute(...)`, and best-effort `column_property(...)` return typing).
 
 ## Repo layout (where things live)
 
@@ -83,4 +86,4 @@ make update-mypy
 - To release:
   - Bump the version.
   - Tag `vX.Y.Z` and push the tag.
-  - GitHub Actions publishes to PyPI via **trusted publishing** (requires configuring the PyPI project + GitHub environment `pypi`).
+  - GitHub Actions publishes to PyPI via **trusted publishing**

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-mypy-plugin
-Version: 0.12.3
+Version: 0.18.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
@@ -68,11 +68,18 @@ Planned work is tracked in [`ROADMAP.md`](ROADMAP.md).
 - Outer-join `None` propagation in `select(A, B).join(B, isouter=True)` result tuples.
 - Broaden `Session.exec()` / `AsyncSession.exec()` typing to accept SQLAlchemy `Executable` statements (e.g.
   `text(...)`), not just `select(...)`.
+- Optional typed `Session.execute()` / `AsyncSession.execute()` for `select(...)` (opt-in; see `typed_execute`).
 - Accept SQLAlchemy TypeEngine instances in `Field(sa_type=...)` (e.g. `DateTime(timezone=True)`, `String(50)`)
   without `# type: ignore` in strict mode.
 - Accept `model_config = ConfigDict(...)` overrides on SQLModel subclasses in strict mode.
 - Compatible with `pydantic.mypy` **when `sqlmodel_mypy.plugin` is listed first**.
 
+## Install
+
+```bash
+uv add sqlmodel-mypy-plugin
+```
+
 ## Install (dev)
 
 Prereqs: **Python 3.10+** and [`uv`](https://docs.astral.sh/uv/).
@@ -119,6 +126,9 @@ Supported options:
   `__init__` / `model_construct` / constructor signatures, so mypy reports unexpected keyword arguments.
 - **`warn_untyped_fields`** (default: `true`): When `true`, emit error code `sqlmodel-field` for untyped
   declarations like `x = Field(...)` / `x = Relationship(...)` (use `x: T = ...` instead).
+- **`typed_execute`** (default: `false`): When `true`, type SQLModel’s deprecated `Session.execute()` /
+  `AsyncSession.execute()` for common `select(...)` statements by recovering `Result[...]` generics. This is meant to
+  reduce “type clutter” during migrations; prefer `Session.exec()` for new code.
 - **`debug_dataclass_transform`** (default: `false`): **Advanced/debug-only**. When `true`, keep SQLModel’s
   `__dataclass_transform__` handling enabled in mypy (useful for debugging plugin interactions; not recommended
   for normal use).
@@ -130,6 +140,7 @@ Supported options:
 init_typed = false
 init_forbid_extra = false
 warn_untyped_fields = true
+typed_execute = false
 debug_dataclass_transform = false
 ```
 
@@ -140,12 +151,15 @@ debug_dataclass_transform = false
 init_typed = false
 init_forbid_extra = false
 warn_untyped_fields = true
+typed_execute = false
 debug_dataclass_transform = false
 ```
 
 ## Error codes
 
 - `sqlmodel-field`: field-related plugin errors (e.g. untyped `x = Field(...)`).
+- `sqlmodel-plugin-order`: plugin ordering errors (e.g. `pydantic.mypy` enabled before `sqlmodel_mypy.plugin`).
+  Fix: list `sqlmodel_mypy.plugin` first (see [Enable in mypy](#enable-in-mypy)).
 
 ## SQL expression typing
 
@@ -170,13 +184,22 @@ tbl = User.__table__
 
 ### `getattr(Model, "field")` support
 
-If you build query filters dynamically, `getattr(Model, "field")` with a **string literal** is typed the same as
-direct `Model.field` access on `table=True` models:
+If you build query filters dynamically, `getattr(Model, "field")` with a **string literal** (or a `Final` / string
+`Literal[...]` name) is typed the same as direct `Model.field` access on `table=True` models:
 
 ```py
 stmt = select(User).where(getattr(User, "name").like("%x%"))
 ```
 
+Example using a `Final` constant:
+
+```py
+from typing import Final
+
+FIELD: Final = "name"
+stmt = select(User).where(getattr(User, FIELD).like("%x%"))
+```
+
 Non-literal names (runtime strings) are intentionally left as `Any` (you’ll still need a cast or a different
 pattern).
 
@@ -220,6 +243,23 @@ Limitations:
 - Mypy can’t express “either field name or alias is required”, so aliased required fields may not be reported as
   missing at type-check time.
 
+## Persisted model helpers (opt-in)
+
+Strict typing + SQLModel often means table-model IDs start as `None` and are populated after flush/commit/refresh
+(see [SQLModel: Automatic IDs, None, and Refresh](https://sqlmodel.tiangolo.com/tutorial/automatic-id-none-refresh/)).
+Mypy can’t infer those runtime effects, so you can end up with repeated `assert obj.id is not None`.
+
+This package ships small helpers you can import (they do **not** affect plugin behavior):
+
+```py
+from sqlmodel_mypy import has_id, require_id
+
+hero_id: int = require_id(hero)  # raises ValueError if hero.id is None
+
+if has_id(hero):
+    ok_id: int = hero.id
+```
+
 ## Development
 
 - List available commands: `make help`
@@ -227,7 +267,7 @@ Limitations:
 - Typecheck plugin code: `make typecheck`
 - Run tests: `make test`
 - Run all quality gates: `make check`
-- Update mypy \u201cgolden\u201d outputs: `make update-mypy`
+- Update mypy "golden" outputs: `make update-mypy`
 
 See [`AGENTS.md`](AGENTS.md) for repo conventions and workflow notes.
 

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

@@ -22,11 +22,18 @@ Planned work is tracked in [`ROADMAP.md`](ROADMAP.md).
 - Outer-join `None` propagation in `select(A, B).join(B, isouter=True)` result tuples.
 - Broaden `Session.exec()` / `AsyncSession.exec()` typing to accept SQLAlchemy `Executable` statements (e.g.
   `text(...)`), not just `select(...)`.
+- Optional typed `Session.execute()` / `AsyncSession.execute()` for `select(...)` (opt-in; see `typed_execute`).
 - Accept SQLAlchemy TypeEngine instances in `Field(sa_type=...)` (e.g. `DateTime(timezone=True)`, `String(50)`)
   without `# type: ignore` in strict mode.
 - Accept `model_config = ConfigDict(...)` overrides on SQLModel subclasses in strict mode.
 - Compatible with `pydantic.mypy` **when `sqlmodel_mypy.plugin` is listed first**.
 
+## Install
+
+```bash
+uv add sqlmodel-mypy-plugin
+```
+
 ## Install (dev)
 
 Prereqs: **Python 3.10+** and [`uv`](https://docs.astral.sh/uv/).
@@ -73,6 +80,9 @@ Supported options:
   `__init__` / `model_construct` / constructor signatures, so mypy reports unexpected keyword arguments.
 - **`warn_untyped_fields`** (default: `true`): When `true`, emit error code `sqlmodel-field` for untyped
   declarations like `x = Field(...)` / `x = Relationship(...)` (use `x: T = ...` instead).
+- **`typed_execute`** (default: `false`): When `true`, type SQLModel’s deprecated `Session.execute()` /
+  `AsyncSession.execute()` for common `select(...)` statements by recovering `Result[...]` generics. This is meant to
+  reduce “type clutter” during migrations; prefer `Session.exec()` for new code.
 - **`debug_dataclass_transform`** (default: `false`): **Advanced/debug-only**. When `true`, keep SQLModel’s
   `__dataclass_transform__` handling enabled in mypy (useful for debugging plugin interactions; not recommended
   for normal use).
@@ -84,6 +94,7 @@ Supported options:
 init_typed = false
 init_forbid_extra = false
 warn_untyped_fields = true
+typed_execute = false
 debug_dataclass_transform = false
 ```
 
@@ -94,12 +105,15 @@ debug_dataclass_transform = false
 init_typed = false
 init_forbid_extra = false
 warn_untyped_fields = true
+typed_execute = false
 debug_dataclass_transform = false
 ```
 
 ## Error codes
 
 - `sqlmodel-field`: field-related plugin errors (e.g. untyped `x = Field(...)`).
+- `sqlmodel-plugin-order`: plugin ordering errors (e.g. `pydantic.mypy` enabled before `sqlmodel_mypy.plugin`).
+  Fix: list `sqlmodel_mypy.plugin` first (see [Enable in mypy](#enable-in-mypy)).
 
 ## SQL expression typing
 
@@ -124,13 +138,22 @@ tbl = User.__table__
 
 ### `getattr(Model, "field")` support
 
-If you build query filters dynamically, `getattr(Model, "field")` with a **string literal** is typed the same as
-direct `Model.field` access on `table=True` models:
+If you build query filters dynamically, `getattr(Model, "field")` with a **string literal** (or a `Final` / string
+`Literal[...]` name) is typed the same as direct `Model.field` access on `table=True` models:
 
 ```py
 stmt = select(User).where(getattr(User, "name").like("%x%"))
 ```
 
+Example using a `Final` constant:
+
+```py
+from typing import Final
+
+FIELD: Final = "name"
+stmt = select(User).where(getattr(User, FIELD).like("%x%"))
+```
+
 Non-literal names (runtime strings) are intentionally left as `Any` (you’ll still need a cast or a different
 pattern).
 
@@ -174,6 +197,23 @@ Limitations:
 - Mypy can’t express “either field name or alias is required”, so aliased required fields may not be reported as
   missing at type-check time.
 
+## Persisted model helpers (opt-in)
+
+Strict typing + SQLModel often means table-model IDs start as `None` and are populated after flush/commit/refresh
+(see [SQLModel: Automatic IDs, None, and Refresh](https://sqlmodel.tiangolo.com/tutorial/automatic-id-none-refresh/)).
+Mypy can’t infer those runtime effects, so you can end up with repeated `assert obj.id is not None`.
+
+This package ships small helpers you can import (they do **not** affect plugin behavior):
+
+```py
+from sqlmodel_mypy import has_id, require_id
+
+hero_id: int = require_id(hero)  # raises ValueError if hero.id is None
+
+if has_id(hero):
+    ok_id: int = hero.id
+```
+
 ## Development
 
 - List available commands: `make help`
@@ -181,7 +221,7 @@ Limitations:
 - Typecheck plugin code: `make typecheck`
 - Run tests: `make test`
 - Run all quality gates: `make check`
-- Update mypy \u201cgolden\u201d outputs: `make update-mypy`
+- Update mypy "golden" outputs: `make update-mypy`
 
 See [`AGENTS.md`](AGENTS.md) for repo conventions and workflow notes.
 

{sqlmodel_mypy_plugin-0.12.3 → sqlmodel_mypy_plugin-0.18.0}/ROADMAP.md

@@ -23,7 +23,7 @@
   - 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”
+  - **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()`).
@@ -31,9 +31,9 @@
 
 ## v0.4 (Docs-aligned relationship constructors) - DONE
 
-**Motivation**: SQLModel’s official docs pass relationship attributes in constructors (e.g. `Hero(team=team)`,
+**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”
+`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)**
@@ -63,17 +63,17 @@ errors for documented patterns.
     pattern (and keep types conservative).
   - Update/add mypy integration tests to match the chosen strategy.
 
-## v0.5 (Model-kind awareness + reduce “surprising” typing) - DONE
+## 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.
+  - 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
+  - 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.
@@ -94,20 +94,20 @@ errors for documented patterns.
 - **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).
+  - 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
+**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.
+`# 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):
+  - 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`
@@ -122,7 +122,7 @@ errors for documented patterns.
     touching runtime behavior.
 
 - **Tests**
-  - Add a mypy integration module that reproduces the failure in strict mode and asserts it’s fixed without
+  - 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))`
@@ -133,7 +133,7 @@ errors for documented patterns.
 
 **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
+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**
@@ -148,7 +148,7 @@ strict with an “incompatible types in assignment” error (`ConfigDict` vs `SQ
     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"]`
+  - Ensure we don't regress table-model behavior: SQLModel uses `model_config["table"]` and `model_config["registry"]`
     at runtime (see `SQLModelMetaclass.__new__`).
 
 - **Tests**
@@ -160,8 +160,8 @@ strict with an “incompatible types in assignment” error (`ConfigDict` vs `SQ
 ## 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.
+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):
@@ -171,26 +171,26 @@ can trigger “No overload variant of `select` matches argument types …” eve
     - `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.:
+  - **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.
+  - 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
+## 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`.
+- **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.
 
@@ -201,7 +201,7 @@ models do provide this at runtime for `table=True`, but type checkers can miss i
 
 - **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`).
+    when stubs don't expose `Table`).
 - **Tests**
   - Add mypy integration coverage for `Model.__table__` and `Session.get` / `AsyncSession.get` with SQLModel
     table models.
@@ -212,29 +212,7 @@ models do provide this at runtime for `table=True`, but type checkers can miss i
 - Best-effort typing for `column_property(...)` return type (infer `Mapped[T]`) to support
   `Model._foo = column_property(...)` patterns.
 
-## v0.13 (SQLModel docs parity suite) - TODO
-
-**Motivation**: the north star is “SQLModel as documented works under `mypy --strict` with minimal casts/ignores”.
-We should lock this down with a dedicated docs-parity integration suite (beyond the current focused unit-style
-mypy modules).
-
-- **Add docs-derived mypy integration modules**
-  - Create minimal, type-focused modules under `tests/mypy/modules/` that mirror official docs patterns (as close
-    as possible, but stripped of runtime/demo noise).
-  - Add them to `tests/mypy/test_mypy.py` and commit golden outputs under `tests/mypy/outputs/**`.
-  - Target doc pages / patterns:
-    - Connected-data joins and outer-joins:
-      - Docs: `https://sqlmodel.tiangolo.com/tutorial/connect/read-connected-data/`
-    - Relationship attribute creation/update patterns (constructor kwargs + mutation):
-      - Docs: `https://sqlmodel.tiangolo.com/tutorial/relationship-attributes/create-and-update-relationships/`
-    - Many-to-many relationship creation patterns:
-      - Docs: `https://sqlmodel.tiangolo.com/tutorial/many-to-many/create-data/`
-    - Update patterns using `sqlmodel_update()` / `model_dump(exclude_unset=True)`:
-      - Docs: `https://sqlmodel.tiangolo.com/tutorial/fastapi/update/`
-      - Source: `https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/main.py` (`SQLModel.sqlmodel_update`)
-  - Ensure strict-mode expectations are explicit (via `# MYPY:` comments and/or `reveal_type(...)` assertions).
-
-## v0.14 (`typing.Annotated[...]` field metadata support) - TODO
+## 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
@@ -252,11 +230,11 @@ signatures (required/optional + alias kwargs) when `Field(...)` metadata lives i
       (`_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):
+    - `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) - TODO
+## 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
@@ -273,17 +251,99 @@ signatures (required/optional + alias kwargs) when `Field(...)` metadata lives i
   - 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) - TODO
+## 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
+**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
+  - 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.12.3 → sqlmodel_mypy_plugin-0.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlmodel-mypy-plugin"
-version = "0.12.3"
+version = "0.18.0"
 description = "Mypy plugin for SQLModel (better constructor/Field typing)."
 readme = "README.md"
 requires-python = ">=3.10"

sqlmodel_mypy_plugin-0.18.0/src/sqlmodel_mypy/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.18.0"
+
+from .persisted import HasId, HasOptionalId, has_id, require_id
+
+__all__ = ["__version__", "HasId", "HasOptionalId", "has_id", "require_id"]

sqlmodel_mypy_plugin-0.18.0/src/sqlmodel_mypy/persisted.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Protocol, TypeVar
+
+from typing_extensions import TypeIs
+
+TId_co = TypeVar("TId_co", covariant=True)
+
+
+class HasOptionalId(Protocol[TId_co]):
+    """An object with an optional primary key (populated later by the DB)."""
+
+    @property
+    def id(self) -> TId_co | None: ...
+
+
+class HasId(HasOptionalId[TId_co], Protocol[TId_co]):
+    """An object with a non-optional primary key."""
+
+    @property
+    def id(self) -> TId_co: ...
+
+
+def has_id(obj: HasOptionalId[TId_co]) -> TypeIs[HasId[TId_co]]:
+    """Return True if `obj.id` is not None, and narrow `obj.id` accordingly."""
+
+    return obj.id is not None
+
+
+def require_id(obj: HasOptionalId[TId_co]) -> TId_co:
+    """Return `obj.id` if present; raise if it's None."""
+
+    if obj.id is None:
+        raise ValueError("Expected object to have a non-None `id` (persisted object).")
+    return obj.id