sqlmodel-mypy-plugin 0.12.0__py3-none-any.whl

sqlmodel_mypy_plugin-0.12.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+sqlmodel_mypy/__init__.py,sha256=2JeqbMHTaN5gXh4SZSyewQh4BVssJaOjJAWvvPC2N58,50
+sqlmodel_mypy/plugin.py,sha256=C35PWP1xbC6jmfnXc5o2y73py1y1XSGv-jNI0FjnOBI,45772
+sqlmodel_mypy/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+sqlmodel_mypy/transform.py,sha256=7826ZoIqgfPHPsOqJojxWREiE9W4IeGFko9rvp1Rufo,30607
+sqlmodel_mypy_plugin-0.12.0.dist-info/METADATA,sha256=-QcqmPGwKPIDYT__Imi_8c9wR1-nLMlFLuHf9O918v8,7684
+sqlmodel_mypy_plugin-0.12.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sqlmodel_mypy_plugin-0.12.0.dist-info/licenses/LICENSE,sha256=2vTtTMBZTlDHJyeU3ehwS7VdCCnprwCnVvv2q52NUJ8,1062
+sqlmodel_mypy_plugin-0.12.0.dist-info/RECORD,,

sqlmodel_mypy_plugin-0.12.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sqlmodel_mypy_plugin-0.12.0.dist-info/licenses/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.