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

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

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

{sqlmodel_mypy_plugin-0.16.0 → sqlmodel_mypy_plugin-0.19.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.16.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.16.0 → sqlmodel_mypy_plugin-0.19.0}/PKG-INFO

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

{sqlmodel_mypy_plugin-0.16.0 → sqlmodel_mypy_plugin-0.19.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).
 

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

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

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