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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-mypy-plugin
-Version: 0.12.3
+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
@@ -220,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`
@@ -227,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.3 → sqlmodel_mypy_plugin-0.16.0}/README.md

@@ -174,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`
@@ -181,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.3 → sqlmodel_mypy_plugin-0.16.0}/ROADMAP.md

@@ -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
@@ -256,7 +234,7 @@ signatures (required/optional + alias kwargs) when `Field(...)` metadata lives i
     - 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,7 +251,7 @@ 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
@@ -287,3 +265,47 @@ repeated `assert obj.id is not None` (type clutter).
     - `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.3 → sqlmodel_mypy_plugin-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlmodel-mypy-plugin"
-version = "0.12.3"
+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

{sqlmodel_mypy_plugin-0.12.3 → sqlmodel_mypy_plugin-0.16.0}/src/sqlmodel_mypy/plugin.py

@@ -154,7 +154,7 @@ SQLMODEL_SESSION_EXEC_FULLNAME = "sqlmodel.orm.session.Session.exec"
 SQLMODEL_ASYNC_SESSION_EXEC_FULLNAME = "sqlmodel.ext.asyncio.session.AsyncSession.exec"
 
 # Increment when plugin changes should invalidate mypy cache.
-__version__ = 17
+__version__ = 20
 
 
 class _CollectedField(NamedTuple):
@@ -187,6 +187,19 @@ def _is_table_model(info: TypeInfo) -> bool:
     if kw is not None:
         return _is_bool_nameexpr(kw, True)
 
+    # Prefer persisted metadata when the class-body AST isn't available
+    # (common in incremental mode when loading modules from cache).
+    metadata = getattr(info, "metadata", None)
+    md = metadata.get(METADATA_KEY) if isinstance(metadata, dict) else None
+    if isinstance(md, dict):
+        md_table = md.get("is_table_model")
+        if isinstance(md_table, bool):
+            return md_table
+        # Backwards-compatible alias for older metadata shapes.
+        md_table = md.get("table")
+        if isinstance(md_table, bool):
+            return md_table
+
     # Inherit `table=True` from bases if present.
     for base in info.mro[1:]:
         if base.fullname == SQLMODEL_BASEMODEL_FULLNAME:
@@ -194,6 +207,10 @@ def _is_table_model(info: TypeInfo) -> bool:
         kw = base.defn.keywords.get("table")
         if kw is not None and _is_bool_nameexpr(kw, True):
             return True
+        base_metadata = getattr(base, "metadata", None)
+        base_md = base_metadata.get(METADATA_KEY) if isinstance(base_metadata, dict) else None
+        if isinstance(base_md, dict) and base_md.get("is_table_model") is True:
+            return True
     return False
 
 
@@ -628,9 +645,24 @@ class SQLModelMypyPlugin(Plugin):
         if sym.node.is_classvar:
             return None
 
-        has_default = SQLModelTransformer.get_has_default(stmt)
-        aliases = tuple(SQLModelTransformer.get_field_aliases(stmt))
         init_type = sym.node.type
+        has_default = SQLModelTransformer.get_has_default(stmt)
+        aliases: tuple[str, ...] = tuple(SQLModelTransformer.get_field_aliases(stmt))
+
+        # Prefer semantic-phase metadata when available (keeps checker-time fallback
+        # consistent with plugin-generated signatures, including Annotated Field metadata).
+        md = defining_info.metadata.get(METADATA_KEY)
+        if isinstance(md, dict):
+            fields = md.get("fields")
+            if isinstance(fields, dict):
+                data = fields.get(name)
+                if isinstance(data, dict):
+                    md_has_default = data.get("has_default")
+                    if isinstance(md_has_default, bool):
+                        has_default = md_has_default
+                    md_aliases = data.get("aliases")
+                    if isinstance(md_aliases, list):
+                        aliases = tuple(a for a in md_aliases if isinstance(a, str))
         if init_type is not None and defining_info is not current_info:
             with state.strict_optional_set(api.options.strict_optional):
                 init_type = map_type_from_supertype(init_type, current_info, defining_info)
@@ -1064,6 +1096,108 @@ class SQLModelMypyPlugin(Plugin):
         except Exception:
             return _plugin_any()
 
+    def _typeinfo_from_join_target_expr(self, expr: Expression | None, api: Any) -> TypeInfo | None:
+        """Return a best-effort `TypeInfo` for a join target expression.
+
+        Supports direct model-class targets (e.g. `join(Team)`) and relationship
+        attribute targets (e.g. `join(Hero.team)`).
+        """
+        info = _typeinfo_from_ref_expr(expr)
+        if info is not None:
+            return info
+        return self._typeinfo_from_relationship_join_target(expr, api)
+
+    def _typeinfo_from_relationship_join_target(
+        self, expr: Expression | None, api: Any
+    ) -> TypeInfo | None:
+        """Infer join target model type from `Model.relationship` expressions."""
+        if not isinstance(expr, MemberExpr):
+            return None
+
+        owner_info = _typeinfo_from_ref_expr(expr.expr)
+        if owner_info is None:
+            return None
+        if owner_info.fullname == SQLMODEL_BASEMODEL_FULLNAME:
+            return None
+        if not owner_info.has_base(SQLMODEL_BASEMODEL_FULLNAME):
+            return None
+        if not _is_table_model(owner_info):
+            return None
+
+        rel_name = expr.name
+        try:
+            _fields, relationships = self._collect_members_for_signature(owner_info, api)
+        except Exception:
+            return None
+
+        rel_type: Type | None = None
+        for rel in relationships:
+            if rel.name == rel_name:
+                rel_type = rel.type
+                break
+        if rel_type is None:
+            return None
+
+        entity_type = self._unwrap_relationship_entity_type(rel_type)
+        if entity_type is None:
+            return None
+        proper = get_proper_type(entity_type)
+        if not isinstance(proper, Instance):
+            return None
+
+        target_info = proper.type
+        if not target_info.has_base(SQLMODEL_BASEMODEL_FULLNAME):
+            return None
+        return target_info
+
+    @classmethod
+    def _unwrap_relationship_entity_type(cls, typ: Type) -> Type | None:
+        """Return the related entity type for relationship annotations.
+
+        Examples:
+        - `Team | None` -> `Team`
+        - `list[Hero]` -> `Hero`
+        - `Mapped[list[Hero]]` -> `Hero`
+        """
+        typ = _unwrap_mapped_type(typ)
+        proper = get_proper_type(typ)
+
+        if isinstance(proper, UnionType):
+            non_none: list[Type] = []
+            for item in proper.items:
+                if isinstance(get_proper_type(item), NoneType):
+                    continue
+                non_none.append(item)
+            if len(non_none) != 1:
+                return None
+            return cls._unwrap_relationship_entity_type(non_none[0])
+
+        if isinstance(proper, Instance):
+            # Relationship types may appear wrapped as ORM descriptor/expression types.
+            if proper.type.fullname in SQLALCHEMY_INSTRUMENTED_ATTRIBUTE_FULLNAMES and proper.args:
+                return cls._unwrap_relationship_entity_type(proper.args[0])
+            if (
+                proper.type.fullname == "sqlalchemy.orm.attributes.QueryableAttribute"
+                and proper.args
+            ):
+                return cls._unwrap_relationship_entity_type(proper.args[0])
+
+            # One-to-many / many-to-many relationships are commonly annotated as `list[T]`.
+            if proper.args and proper.type.fullname in {
+                "builtins.list",
+                "builtins.set",
+                "builtins.frozenset",
+                "collections.abc.Sequence",
+                "typing.Sequence",
+                "typing.List",
+                "typing.Set",
+                "typing.FrozenSet",
+            }:
+                return cls._unwrap_relationship_entity_type(proper.args[0])
+            return typ
+
+        return None
+
     def _sqlalchemy_select_join_like_return_type(
         self, ctx: MethodContext, *, target_positional_index: int, isouter_always: bool
     ) -> Type:
@@ -1080,7 +1214,7 @@ class SQLModelMypyPlugin(Plugin):
                 return ctx.default_return_type
 
         target_expr = _call_get_arg(call, "target", target_positional_index)
-        target_info = _typeinfo_from_ref_expr(target_expr)
+        target_info = self._typeinfo_from_join_target_expr(target_expr, ctx.api)
         if target_info is None:
             return ctx.default_return_type