sqlmodel-mypy-plugin 0.12.2__tar.gz → 0.16.0__tar.gz

{sqlmodel_mypy_plugin-0.12.2 → sqlmodel_mypy_plugin-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-mypy-plugin
-Version: 0.12.2
+Version: 0.16.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
@@ -168,6 +168,18 @@ You can also use SQLAlchemy table metadata attributes without `attr-defined` noi
 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:
+
+```py
+stmt = select(User).where(getattr(User, "name").like("%x%"))
+```
+
+Non-literal names (runtime strings) are intentionally left as `Any` (you’ll still need a cast or a different
+pattern).
+
 ### Relationship comparator typing
 
 Relationship attributes declared via `Relationship(...)` are typed as SQLAlchemy expressions at class level,
@@ -181,9 +193,11 @@ stmt = select(Team).where(Team.heroes.contains(hero_obj))
 
 ### Out of scope
 
-- **`column_property(...)` and similar SQLAlchemy helpers**: this plugin doesn’t try to “fix” the *declaration-site*
-  typing for SQLAlchemy-only APIs that aren’t part of SQLModel’s surface area. Prefer SQLAlchemy-typed patterns like
-  `Mapped[...]` / `InstrumentedAttribute[...]` (or local casts/`# type: ignore` if needed).
+- **Most SQLAlchemy-only declaration helpers**: this plugin doesn’t try to “fix” the full *declaration-site* typing
+  for SQLAlchemy ORM APIs that aren’t part of SQLModel’s surface area.
+  - Exception: best-effort return typing for `column_property(...)` (infers `Mapped[T]` from `ScalarSelect[T]` /
+    `ColumnElement[T]`) to support patterns like `Model._foo = column_property(...)` combined with
+    `getattr(Model, "_foo")` in query builders.
 - **Pydantic `@computed_field`**: not touched by this plugin (it should type-check via normal property typing / Pydantic
   typing).
 
@@ -206,6 +220,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`
@@ -213,7 +244,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.2 → sqlmodel_mypy_plugin-0.16.0}/README.md

@@ -122,6 +122,18 @@ You can also use SQLAlchemy table metadata attributes without `attr-defined` noi
 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:
+
+```py
+stmt = select(User).where(getattr(User, "name").like("%x%"))
+```
+
+Non-literal names (runtime strings) are intentionally left as `Any` (you’ll still need a cast or a different
+pattern).
+
 ### Relationship comparator typing
 
 Relationship attributes declared via `Relationship(...)` are typed as SQLAlchemy expressions at class level,
@@ -135,9 +147,11 @@ stmt = select(Team).where(Team.heroes.contains(hero_obj))
 
 ### Out of scope
 
-- **`column_property(...)` and similar SQLAlchemy helpers**: this plugin doesn’t try to “fix” the *declaration-site*
-  typing for SQLAlchemy-only APIs that aren’t part of SQLModel’s surface area. Prefer SQLAlchemy-typed patterns like
-  `Mapped[...]` / `InstrumentedAttribute[...]` (or local casts/`# type: ignore` if needed).
+- **Most SQLAlchemy-only declaration helpers**: this plugin doesn’t try to “fix” the full *declaration-site* typing
+  for SQLAlchemy ORM APIs that aren’t part of SQLModel’s surface area.
+  - Exception: best-effort return typing for `column_property(...)` (infers `Mapped[T]` from `ScalarSelect[T]` /
+    `ColumnElement[T]`) to support patterns like `Model._foo = column_property(...)` combined with
+    `getattr(Model, "_foo")` in query builders.
 - **Pydantic `@computed_field`**: not touched by this plugin (it should type-check via normal property typing / Pydantic
   typing).
 
@@ -160,6 +174,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`
@@ -167,7 +198,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.2 → sqlmodel_mypy_plugin-0.16.0}/ROADMAP.md

@@ -22,7 +22,12 @@
   - 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).
-- Avoid forcing users to order plugins (`sqlmodel_mypy.plugin` vs `pydantic.mypy`) for correct SQLModel resolution.
+- **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
 
@@ -200,3 +205,107 @@ models do provide this at runtime for `table=True`, but type checkers can miss i
 - **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)
+
+**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 (Recognize `table=True` via `model_config["table"]`, not just class kwargs)
+
+**Motivation**: SQLModel’s runtime `is_table_model_class()` checks `model_config.get("table")`, so a class can be a
+table model even when it isn’t declared as `class Model(SQLModel, table=True)`. Today our plugin/transformer only
+looks at the class keyword, so “table-only” behaviors may not activate (expression typing, relationship kwargs in
+constructor signatures, `__table__`, etc.).
+
+- **Detect table models via `model_config` (metadata-driven)**
+  - Extend semantic analysis in `src/sqlmodel_mypy/transform.py` to detect a statically-known class-body assignment like:
+    - `model_config = ConfigDict(table=True)` or equivalent SQLModel config helpers
+  - Persist the result in `TypeInfo.metadata["sqlmodel-mypy-metadata"]`, then update `_is_table_model(...)` in:
+    - `src/sqlmodel_mypy/plugin.py`
+    - `src/sqlmodel_mypy/transform.py`
+    to consult metadata first (then fall back to `table=True` in the class definition).
+  - Source references:
+    - SQLModel metaclass reads config: `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` (`is_table_model_class`)
+- **Tests**
+  - Add mypy integration coverage for a table model enabled via `model_config` and assert the same behavior as
+    `table=True`:
+    - class attribute expression typing (e.g. `User.id.in_([1])`)
+    - constructor accepts relationship kwargs when configured (`init_forbid_extra=true`)
+    - `User.__table__` is typed and present

{sqlmodel_mypy_plugin-0.12.2 → sqlmodel_mypy_plugin-0.16.0}/pyproject.toml

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

sqlmodel_mypy_plugin-0.16.0/src/sqlmodel_mypy/__init__.py

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

sqlmodel_mypy_plugin-0.16.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