sqlmodel-mypy-plugin 0.12.0__tar.gz

sqlmodel_mypy_plugin-0.12.0/.gitignore

@@ -0,0 +1,23 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.egg/
+
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.uv-cache
+.uv_cache
+coverage/
+.coverage
+.coverage.*
+htmlcov/
+
+.venv/
+venv/
+ENV/
+
+dist/
+build/

sqlmodel_mypy_plugin-0.12.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

sqlmodel_mypy_plugin-0.12.0/AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md
+
+# AGENTS.md (repo workflow & invariants)
+
+This repo builds a **mypy plugin** for **SQLModel**.
+
+## Non-negotiable quality gates (every session / every PR)
+
+Before you consider work "done", you **must** have a green:
+
+```bash
+make check
+```
+
+This includes **tests** and a **coverage gate**: **90%+** for the `sqlmodel_mypy` package.
+
+If your change affects mypy diagnostics or generated signatures, you **must** update and commit golden outputs:
+
+```bash
+make update-mypy
+```
+
+## Toolchain / stack
+
+- **Language**: Python (plugin code + tests)
+- **Runtime**: Python **>= 3.10** (CI tests multiple versions)
+- **Package manager / runner**: `uv` (lockfile-driven, reproducible)
+- **Lint/format**: `ruff`
+- **Typecheck**: `mypy` (plugin uses mypy internal APIs)
+- **Tests**: `pytest`
+- **Build backend**: `hatchling`
+
+`uv.lock` is the source of truth for dependency resolution in CI and development.
+
+## Quick commands (canonical)
+
+- **Help**: `make help`
+- **Install (locked dev env)**: `make install`
+- **Format**: `make fmt`
+- **Lint**: `make lint`
+- **Typecheck**: `make typecheck`
+- **Tests**: `make test`
+- **All gates (what CI runs)**: `make check`
+- **Update golden mypy outputs**: `make update-mypy`
+- **Build artifacts**: `make build`
+
+## What the plugin does (scope)
+
+- Collects SQLModel fields and determines required/optional kwargs based on `sqlmodel.Field(...)`.
+- **Ignores** `sqlmodel.Relationship(...)` when generating constructor kwargs.
+- Synthesizes `__init__` and `model_construct` signatures for SQLModel subclasses during mypy semantic analysis.
+
+## Repo layout (where things live)
+
+- `src/sqlmodel_mypy/plugin.py`: mypy plugin entrypoint, config parsing, cache invalidation.
+- `src/sqlmodel_mypy/transform.py`: SQLModel class transformation (collect fields, generate methods).
+- `tests/mypy/`: integration tests that run mypy on small modules and commit merged outputs
+  - `tests/mypy/configs/`: mypy configs (`*.ini`, `*.toml`)
+  - `tests/mypy/modules/`: tiny python modules checked by mypy
+  - `tests/mypy/outputs/`: golden outputs produced by merging mypy output into sources
+
+## Invariants / gotchas (do not break these)
+
+- **Plugin ordering matters**: if a user enables both `sqlmodel_mypy.plugin` and `pydantic.mypy`, this plugin must come **first**, otherwise Pydantic's plugin may "claim" SQLModel classes (see `README.md`).
+- **Incremental mode safety**:
+  - Avoid global state.
+  - Persist per-class data in `TypeInfo.metadata` under a **JSON-serializable** key.
+  - Current key: `sqlmodel-mypy-metadata` (see `src/sqlmodel_mypy/transform.py`).
+- **Idempotency**: class hooks may run multiple times. Code must tolerate re-entry and partial analysis.
+  - When types/defs aren't ready, call `api.defer()` and exit early.
+- **Cache invalidation is mandatory**:
+  - Mypy caches plugin-produced metadata. If you change plugin behavior, bump `__version__` in `src/sqlmodel_mypy/plugin.py`.
+  - This value is included in `report_config_data()` and forces mypy to invalidate its cache.
+
+## Golden test policy (how we lock down behavior)
+
+- If you change expected mypy messages/signatures, regenerate outputs with `make update-mypy` and commit the changes under `tests/mypy/outputs/**`.
+- Keep test modules minimal and focused: add a new file in `tests/mypy/modules/` and wire it into `tests/mypy/test_mypy.py`.
+
+## Release process (PyPI, trusted publishing)
+
+- Version is defined in `pyproject.toml`.
+- 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`).

sqlmodel_mypy_plugin-0.12.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sqlmodel_mypy_plugin-0.12.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: sqlmodel-mypy-plugin
+Version: 0.12.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
+License: MIT License
+        
+        Copyright (c) 2026 Artem
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: mypy,plugin,pydantic,sqlalchemy,sqlmodel,typing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: mypy>=1.19.1
+Requires-Dist: typing-extensions>=4.10.0
+Description-Content-Type: text/markdown
+
+# SQLModel Mypy plugin
+
+Mypy plugin that improves type checking for [`SQLModel`](https://github.com/fastapi/sqlmodel) models.
+
+## Status
+
+Early/experimental. Implemented scope (supported today):
+
+Planned work is tracked in [`ROADMAP.md`](ROADMAP.md).
+
+- Generate correct `__init__` / `model_construct` signatures for SQLModel models:
+  - treat `sqlmodel.Field(...)` required/optional correctly
+  - accept `sqlmodel.Relationship(...)` kwargs for `table=True` models
+  - accept common `Field(...)` alias kwargs (`alias` / `validation_alias`) when statically known
+- Improve SQLAlchemy expression typing for **class** attribute access on `table=True` models (e.g. `User.id`,
+  `User.name`, `Team.heroes`).
+- Common SQLAlchemy helpers that operate on expressions / selects (e.g. `.label(...)`, `selectinload(...)`,
+  `execution_options(...)`) work without spurious mypy errors.
+- Expose SQLAlchemy table metadata on `table=True` models (e.g. `User.__table__`).
+- Relationship comparator typing on relationship attributes (e.g. `Team.heroes.any(...)`, `Hero.team.has(...)`,
+  `Team.heroes.contains(...)`).
+- 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(...)`.
+- 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` in either plugin order.
+
+## Install (dev)
+
+Prereqs: **Python 3.10+** and [`uv`](https://docs.astral.sh/uv/).
+
+```bash
+make install
+```
+
+Run the full quality gate suite (same as CI):
+
+```bash
+make check
+```
+
+## Enable in mypy
+
+`mypy.ini`:
+
+```ini
+[mypy]
+plugins = sqlmodel_mypy.plugin
+```
+
+If you also use `pydantic.mypy`, you can list plugins in either order:
+
+```ini
+[mypy]
+plugins = sqlmodel_mypy.plugin, pydantic.mypy
+# or:
+# plugins = pydantic.mypy, sqlmodel_mypy.plugin
+```
+
+## Plugin configuration
+
+`mypy.ini`:
+
+```ini
+[sqlmodel-mypy]
+init_typed = false
+init_forbid_extra = false
+warn_untyped_fields = true
+```
+
+`pyproject.toml`:
+
+```toml
+[tool.sqlmodel-mypy]
+init_typed = false
+init_forbid_extra = false
+warn_untyped_fields = true
+```
+
+## Error codes
+
+- `sqlmodel-field`: field-related plugin errors (e.g. untyped `x = Field(...)`).
+
+## SQL expression typing
+
+This plugin adjusts **class attribute** types on `table=True` SQLModel models to behave like SQLAlchemy
+expressions, so you can write queries without `col()`:
+
+```py
+from sqlmodel import Field, SQLModel, select
+
+class User(SQLModel, table=True):
+    id: int = Field(primary_key=True)
+    name: str = Field()
+
+stmt = select(User).where(User.name.like("%x%"))
+```
+
+You can also use SQLAlchemy table metadata attributes without `attr-defined` noise:
+
+```py
+tbl = User.__table__
+```
+
+### Relationship comparator typing
+
+Relationship attributes declared via `Relationship(...)` are typed as SQLAlchemy expressions at class level,
+including common relationship comparators used in query filters:
+
+```py
+stmt = select(Team).where(Team.heroes.any(Hero.name == "x"))
+stmt = select(Hero).where(Hero.team.has(Team.name == "t"))
+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).
+- **Pydantic `@computed_field`**: not touched by this plugin (it should type-check via normal property typing / Pydantic
+  typing).
+
+## Typing strategy (defaults)
+
+- **Plugin hooks**: SQLModel-specific behavior (constructor signatures, `table=True` expression typing, etc.).
+- **SQLAlchemy typing**: relied upon for core SQL/ORM typing wherever possible.
+- **Stub overlays**: only for upstream gaps that can’t be addressed cleanly via hooks (prefer upstream fixes first).
+
+## Field aliases in constructor kwargs
+
+If you use `Field(alias=...)` (or `validation_alias=...` / `schema_extra={"validation_alias": ...}`), the plugin
+adds the alias name as an accepted keyword argument in generated `__init__` / `model_construct` signatures.
+This avoids false-positive “unexpected keyword argument” errors when `init_forbid_extra=true`.
+
+Limitations:
+
+- Only **string-literal** aliases are recognized (e.g. `Field(alias=\"full_name\")`).
+- Aliases that are not valid Python identifiers (or that collide with other parameter names) are ignored.
+- 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.
+
+## Development
+
+- List available commands: `make help`
+- Lint/format: `make lint` / `make fmt`
+- Typecheck plugin code: `make typecheck`
+- Run tests: `make test`
+- Run all quality gates: `make check`
+- Update mypy \u201cgolden\u201d outputs: `make update-mypy`
+
+See [`AGENTS.md`](AGENTS.md) for repo conventions and workflow notes.
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md).
+
+## Code of conduct
+
+See [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).

sqlmodel_mypy_plugin-0.12.0/README.md

@@ -0,0 +1,162 @@
+# SQLModel Mypy plugin
+
+Mypy plugin that improves type checking for [`SQLModel`](https://github.com/fastapi/sqlmodel) models.
+
+## Status
+
+Early/experimental. Implemented scope (supported today):
+
+Planned work is tracked in [`ROADMAP.md`](ROADMAP.md).
+
+- Generate correct `__init__` / `model_construct` signatures for SQLModel models:
+  - treat `sqlmodel.Field(...)` required/optional correctly
+  - accept `sqlmodel.Relationship(...)` kwargs for `table=True` models
+  - accept common `Field(...)` alias kwargs (`alias` / `validation_alias`) when statically known
+- Improve SQLAlchemy expression typing for **class** attribute access on `table=True` models (e.g. `User.id`,
+  `User.name`, `Team.heroes`).
+- Common SQLAlchemy helpers that operate on expressions / selects (e.g. `.label(...)`, `selectinload(...)`,
+  `execution_options(...)`) work without spurious mypy errors.
+- Expose SQLAlchemy table metadata on `table=True` models (e.g. `User.__table__`).
+- Relationship comparator typing on relationship attributes (e.g. `Team.heroes.any(...)`, `Hero.team.has(...)`,
+  `Team.heroes.contains(...)`).
+- 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(...)`.
+- 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` in either plugin order.
+
+## Install (dev)
+
+Prereqs: **Python 3.10+** and [`uv`](https://docs.astral.sh/uv/).
+
+```bash
+make install
+```
+
+Run the full quality gate suite (same as CI):
+
+```bash
+make check
+```
+
+## Enable in mypy
+
+`mypy.ini`:
+
+```ini
+[mypy]
+plugins = sqlmodel_mypy.plugin
+```
+
+If you also use `pydantic.mypy`, you can list plugins in either order:
+
+```ini
+[mypy]
+plugins = sqlmodel_mypy.plugin, pydantic.mypy
+# or:
+# plugins = pydantic.mypy, sqlmodel_mypy.plugin
+```
+
+## Plugin configuration
+
+`mypy.ini`:
+
+```ini
+[sqlmodel-mypy]
+init_typed = false
+init_forbid_extra = false
+warn_untyped_fields = true
+```
+
+`pyproject.toml`:
+
+```toml
+[tool.sqlmodel-mypy]
+init_typed = false
+init_forbid_extra = false
+warn_untyped_fields = true
+```
+
+## Error codes
+
+- `sqlmodel-field`: field-related plugin errors (e.g. untyped `x = Field(...)`).
+
+## SQL expression typing
+
+This plugin adjusts **class attribute** types on `table=True` SQLModel models to behave like SQLAlchemy
+expressions, so you can write queries without `col()`:
+
+```py
+from sqlmodel import Field, SQLModel, select
+
+class User(SQLModel, table=True):
+    id: int = Field(primary_key=True)
+    name: str = Field()
+
+stmt = select(User).where(User.name.like("%x%"))
+```
+
+You can also use SQLAlchemy table metadata attributes without `attr-defined` noise:
+
+```py
+tbl = User.__table__
+```
+
+### Relationship comparator typing
+
+Relationship attributes declared via `Relationship(...)` are typed as SQLAlchemy expressions at class level,
+including common relationship comparators used in query filters:
+
+```py
+stmt = select(Team).where(Team.heroes.any(Hero.name == "x"))
+stmt = select(Hero).where(Hero.team.has(Team.name == "t"))
+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).
+- **Pydantic `@computed_field`**: not touched by this plugin (it should type-check via normal property typing / Pydantic
+  typing).
+
+## Typing strategy (defaults)
+
+- **Plugin hooks**: SQLModel-specific behavior (constructor signatures, `table=True` expression typing, etc.).
+- **SQLAlchemy typing**: relied upon for core SQL/ORM typing wherever possible.
+- **Stub overlays**: only for upstream gaps that can’t be addressed cleanly via hooks (prefer upstream fixes first).
+
+## Field aliases in constructor kwargs
+
+If you use `Field(alias=...)` (or `validation_alias=...` / `schema_extra={"validation_alias": ...}`), the plugin
+adds the alias name as an accepted keyword argument in generated `__init__` / `model_construct` signatures.
+This avoids false-positive “unexpected keyword argument” errors when `init_forbid_extra=true`.
+
+Limitations:
+
+- Only **string-literal** aliases are recognized (e.g. `Field(alias=\"full_name\")`).
+- Aliases that are not valid Python identifiers (or that collide with other parameter names) are ignored.
+- 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.
+
+## Development
+
+- List available commands: `make help`
+- Lint/format: `make lint` / `make fmt`
+- Typecheck plugin code: `make typecheck`
+- Run tests: `make test`
+- Run all quality gates: `make check`
+- Update mypy \u201cgolden\u201d outputs: `make update-mypy`
+
+See [`AGENTS.md`](AGENTS.md) for repo conventions and workflow notes.
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md).
+
+## Code of conduct
+
+See [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).