sqlalchemy-pydantic-json 0.0.1a1__py3-none-any.whl

sqlalchemy_pydantic_json/__init__.py

@@ -0,0 +1,5 @@
+"""Pydantic v2 models stored in SQLAlchemy JSON columns, with automatic change tracking."""
+
+from sqlalchemy_pydantic_json._model import EmbeddedPydanticModel, PydanticJSON
+
+__all__ = ["EmbeddedPydanticModel", "PydanticJSON"]

sqlalchemy_pydantic_json/_model.py

@@ -0,0 +1,377 @@
+"""
+Pydantic models stored in SQLAlchemy JSON columns, with full change tracking.
+
+Usage:
+
+    class Address(EmbeddedPydanticModel):
+        city: str = "Helsinki"
+
+    class Settings(EmbeddedPydanticModel):
+        tags: set[str] = set()
+        address: Address = Address()
+
+    class User(Base):
+        ...
+        settings: Mapped[Settings] = mapped_column(Settings.column(), default=Settings)
+        extra: Mapped[Settings | None] = mapped_column(Settings.column())
+
+Any change anywhere inside `user.settings` (attributes, list/dict/set
+mutations, nested models) marks `user` dirty. Use EmbeddedPydanticModel as the base
+for the column's model *and* for all of its submodels.
+"""
+
+from __future__ import annotations
+
+import functools
+import weakref
+from collections.abc import Callable, Iterable
+from typing import Any, Protocol, Self, SupportsIndex, TypeVar, cast, overload
+
+from pydantic import AliasChoices, AliasPath, BaseModel, PrivateAttr
+from pydantic.fields import FieldInfo
+from sqlalchemy import JSON, Dialect
+from sqlalchemy.ext.mutable import Mutable, MutableDict, MutableList, MutableSet
+from sqlalchemy.orm.attributes import flag_modified
+from sqlalchemy.types import TypeDecorator, TypeEngine
+
+__all__ = ["EmbeddedPydanticModel", "PydanticJSON"]
+
+_M = TypeVar("_M", bound=BaseModel)
+_T = TypeVar("_T")
+_KT = TypeVar("_KT")
+_VT = TypeVar("_VT")
+
+
+# --------------------------------------------------------------------------
+# Column type
+# --------------------------------------------------------------------------
+class PydanticJSON(TypeDecorator[_M]):
+    """
+    JSON column type converting to/from a Pydantic model.
+
+    Don't use it directly; use ``Model.column()``, which also enables change
+    tracking (a bare PydanticJSON column would not notice in-place changes).
+    """
+
+    impl: TypeEngine[Any] | type[TypeEngine[Any]] = JSON
+    cache_ok = True
+
+    def __init__(self, model: type[_M], json_type: type[JSON] | JSON = JSON) -> None:
+        # Replaces TypeDecorator.__init__, which would build `impl` from the class attribute.
+        self.model = model
+        self.json_type = json_type(none_as_null=True) if isinstance(json_type, type) else json_type
+        self.impl = self.json_type
+
+    def process_bind_param(self, value: Any, dialect: Dialect) -> Any:
+        if value is None:
+            return None
+        return _validate(self.model, value).model_dump(mode="json", by_alias=True)
+
+    def process_result_value(self, value: Any, dialect: Dialect) -> _M | None:
+        return None if value is None else _validate(self.model, value)
+
+
+# The JSON is stored with the models' aliases (like Pydantic's own `by_alias=True`). Loading also
+# accepts field names, e.g. in rows stored before an alias was added.
+def _validate(model: type[_M], value: Any) -> _M:
+    return model.model_validate(value, by_alias=True, by_name=True)
+
+
+# Marks a model_post_init that sets up the tracking. Pydantic wraps model_post_init in every
+# subclass (because of the private attribute) with functools.wraps, which copies the mark along.
+_LINKS_FIELDS = "_sqlalchemy_pydantic_json_links_fields"
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+def _marked_as_linking(post_init: _F) -> _F:
+    setattr(post_init, _LINKS_FIELDS, True)
+    return post_init
+
+
+def _links_fields(post_init: object) -> bool:
+    """Whether `post_init`, or a function it wraps (functools.wraps), sets up the tracking."""
+    while post_init is not None:
+        if getattr(post_init, _LINKS_FIELDS, False):
+            return True
+        post_init = getattr(post_init, "__wrapped__", None)
+    return False
+
+
+def _linking_post_init(
+    post_init: Callable[[EmbeddedPydanticModel, Any], None],
+) -> Callable[[EmbeddedPydanticModel, Any], None]:
+    @functools.wraps(post_init)
+    def model_post_init(self: EmbeddedPydanticModel, context: Any, /) -> None:
+        post_init(self, context)
+        self._link_fields()  # linking again (if it also called super()) is harmless
+
+    return _marked_as_linking(model_post_init)
+
+
+def _check_aliases_round_trip(model: type[BaseModel]) -> None:
+    """Raise if a field is stored under a name it can't be loaded from again."""
+    for name, field in model.model_fields.items():
+        stored = field.serialization_alias or name
+        if stored not in _loadable_names(name, field):
+            raise TypeError(
+                f"{model.__name__}.{name} is stored as {stored!r} (its serialization alias), "
+                f"but can't be loaded from that name (validation alias: "
+                f"{field.validation_alias!r}). Use the same alias for both, or include "
+                f"{stored!r} in the validation alias with AliasChoices."
+            )
+
+
+def _loadable_names(name: str, field: FieldInfo) -> set[str]:
+    names = {name}
+    aliases = field.validation_alias
+    choices = aliases.choices if isinstance(aliases, AliasChoices) else [aliases]
+    for choice in choices:
+        if isinstance(choice, str):
+            names.add(choice)
+        elif isinstance(choice, AliasPath) and len(choice.path) == 1:
+            names.add(str(choice.path[0]))
+    return names
+
+
+# --------------------------------------------------------------------------
+# Parent links (supports several parents; stale links are pruned lazily)
+# --------------------------------------------------------------------------
+class _Parent(Protocol):
+    """A model or container that can hold tracked values."""
+
+    def _notify(self) -> None: ...
+
+
+class _ParentLinks:
+    __slots__ = ("_refs",)
+
+    def __init__(self) -> None:
+        self._refs: dict[int, weakref.ref[_Parent]] = {}
+
+    def add(self, parent: _Parent) -> None:
+        self._refs[id(parent)] = weakref.ref(parent)
+
+    def notify(self, child: object) -> None:
+        for key, ref in list(self._refs.items()):
+            parent = ref()
+            # a parent that was garbage collected, or no longer holds the
+            # child (popped, replaced, ...), is dropped instead of notified
+            if parent is None or not _holds(parent, child):
+                self._refs.pop(key, None)
+                continue
+            parent._notify()
+
+    # Links aren't part of a model's value; Pydantic's `==` compares private attributes too, so
+    # without this no two models would ever be equal.
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, _ParentLinks) or NotImplemented
+
+    __hash__ = None  # type: ignore[assignment]
+
+    # copies (copy.copy and copy.deepcopy use this too) and pickles start out unlinked
+    def __reduce__(self) -> tuple[type[_ParentLinks], tuple[()]]:
+        return (_ParentLinks, ())
+
+
+def _holds(parent: _Parent, child: object) -> bool:
+    if isinstance(parent, EmbeddedPydanticModel):
+        d = vars(parent)
+        return any(d.get(name) is child for name in type(parent).model_fields)
+    if isinstance(parent, _TrackedDict):
+        return any(v is child for v in cast("_TrackedDict[Any, Any]", parent).values())
+    # the only other parents are lists (set items are never linked)
+    return any(v is child for v in cast("_TrackedList[Any]", parent))
+
+
+def _link(value: Any, parent: _Parent) -> Any:
+    """Return `value` with tracking enabled, linked to `parent`."""
+    tracked: _TrackedList[Any] | _TrackedDict[Any, Any] | _TrackedSet[Any]
+    if isinstance(value, EmbeddedPydanticModel):
+        value._links.add(parent)  # add, not replace: the same instance may live in several places
+        return value
+    if isinstance(value, _TrackedList | _TrackedDict | _TrackedSet):
+        tracked = cast("_TrackedList[Any] | _TrackedDict[Any, Any] | _TrackedSet[Any]", value)
+    elif isinstance(value, list):
+        # a new container has no parents yet, so filling it (which links each item to it)
+        # notifies nobody
+        tracked = _TrackedList()
+        tracked.extend(cast("list[Any]", value))
+    elif isinstance(value, dict):
+        tracked = _TrackedDict()
+        tracked.update(cast("dict[Any, Any]", value))
+    elif isinstance(value, set):  # set items are hashable, so never models/lists/dicts
+        tracked = _TrackedSet(cast("set[Any]", value))
+    else:
+        return value
+    tracked._links.add(parent)
+    return tracked
+
+
+# --------------------------------------------------------------------------
+# Tracked containers (SQLAlchemy's Mutable* already hook every mutating method)
+# --------------------------------------------------------------------------
+class _TrackedContainer:
+    @property
+    def _links(self) -> _ParentLinks:
+        try:
+            links: _ParentLinks = self.__dict__["_links_"]
+        except KeyError:
+            links = self.__dict__["_links_"] = _ParentLinks()
+        return links
+
+    def changed(self) -> None:
+        self._links.notify(self)
+
+    def _notify(self) -> None:  # a child inside this container changed
+        self.changed()
+
+
+# MutableList's and MutableSet's in-place operators (__iadd__, __ior__, ...) don't match list's and
+# set's; that comes from SQLAlchemy.
+class _TrackedList(_TrackedContainer, MutableList[_T]):  # ty: ignore[invalid-method-override]
+    def __setitem__(self, index: SupportsIndex | slice, value: _T | Iterable[_T]) -> None:
+        if isinstance(index, slice):
+            value = [_link(x, self) for x in cast("Iterable[_T]", value)]
+        else:
+            value = _link(value, self)
+        super().__setitem__(index, value)
+
+    def append(self, x: _T) -> None:
+        super().append(_link(x, self))
+
+    def extend(self, x: Iterable[_T]) -> None:
+        super().extend([_link(v, self) for v in x])
+
+    def insert(self, i: SupportsIndex, x: _T) -> None:
+        super().insert(i, _link(x, self))
+
+
+class _TrackedDict(_TrackedContainer, MutableDict[_KT, _VT]):
+    def __setitem__(self, key: _KT, value: _VT) -> None:
+        super().__setitem__(key, _link(value, self))
+
+    # same overloads as MutableDict.setdefault
+    @overload
+    def setdefault(
+        self: _TrackedDict[_KT, _T | None], key: _KT, value: None = None
+    ) -> _T | None: ...
+
+    @overload
+    def setdefault(self, key: _KT, value: _VT) -> _VT: ...
+
+    def setdefault(self, key: _KT, value: object = None) -> object:
+        return super().setdefault(key, _link(value, self))
+
+    def update(self, *a: Any, **kw: _VT) -> None:
+        super().update({k: _link(v, self) for k, v in dict(*a, **kw).items()})
+
+
+class _TrackedSet(_TrackedContainer, MutableSet[_T]):  # ty: ignore[invalid-method-override]
+    pass
+
+
+# --------------------------------------------------------------------------
+# The base model
+# --------------------------------------------------------------------------
+class EmbeddedPydanticModel(Mutable, BaseModel):
+    """Base class for models stored in a JSON column, and for their submodels."""
+
+    _links: _ParentLinks = PrivateAttr(default_factory=_ParentLinks)
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+        _check_aliases_round_trip(cls)
+        # A model_post_init of the subclass's own also sets up tracking, whether or not it calls
+        # super().model_post_init().
+        own_post_init = cls.__dict__.get("model_post_init")
+        if own_post_init is not None and not _links_fields(own_post_init):
+            setattr(cls, "model_post_init", _linking_post_init(own_post_init))  # noqa: B010
+
+    @_marked_as_linking
+    def model_post_init(self, context: Any, /) -> None:
+        self._link_fields()
+
+    def _link_fields(self) -> None:
+        d = vars(self)
+        for name in type(self).model_fields:
+            d[name] = _link(d[name], self)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        super().__setattr__(name, value)
+        if name in type(self).model_fields:
+            d = vars(self)
+            d[name] = _link(d[name], self)
+            self._notify()
+
+    def __delattr__(self, name: str) -> None:
+        super().__delattr__(name)
+        self._notify()
+
+    def _notify(self) -> None:
+        self.changed()
+        self._links.notify(self)
+
+    def changed(self) -> None:
+        """
+        Flag every ORM row that currently holds this instance as modified.
+
+        Like Mutable.changed(), but skips (and forgets) rows that no longer hold
+        this exact instance, e.g. expired after a commit or since reassigned.
+        """
+        for state, key in list(self._parents.items()):
+            obj = state.obj()
+            if obj is None or state.dict.get(key) is not self:
+                self._parents.pop(state, None)
+                continue
+            flag_modified(obj, key)
+
+    # --- copies are independent: not linked to the original's parents/rows ---
+    def __copy__(self) -> Self:
+        new = super().__copy__()
+        d = vars(new)
+        for name in type(new).model_fields:  # a shallow copy shares containers; give it its own
+            v = d[name]
+            if isinstance(v, list | dict | set):
+                d[name] = cast("list[Any] | dict[Any, Any] | set[Any]", v).copy()
+        return new._detached()
+
+    def __deepcopy__(self, memo: dict[int, Any] | None = None) -> Self:
+        return super().__deepcopy__(memo)._detached()
+
+    def _detached(self) -> Self:
+        vars(self).pop("_parents", None)
+        self._links = _ParentLinks()
+        self._link_fields()
+        return self
+
+    def __getstate__(self) -> dict[Any, Any]:
+        state = super().__getstate__()
+        state["__dict__"] = {k: v for k, v in state["__dict__"].items() if k != "_parents"}
+        return state
+
+    def __setstate__(self, state: dict[Any, Any]) -> None:
+        super().__setstate__(state)
+        self._link_fields()
+
+    # --- SQLAlchemy Mutable hooks ---
+    @classmethod
+    def coerce(cls, key: str, value: Any) -> Self | None:
+        if value is None or isinstance(value, cls):
+            return value
+        if isinstance(value, dict):
+            return _validate(cls, value)
+        return cast("Self | None", super().coerce(key, value))
+
+    @classmethod
+    def column(cls, json_type: type[JSON] | JSON = JSON) -> PydanticJSON[Self]:
+        """
+        Column type for ``mapped_column()``, with change tracking enabled.
+
+        `json_type` is the underlying column type: the generic ``JSON`` by default, or e.g.
+        PostgreSQL's ``JSONB``. A class is created with ``none_as_null=True``, so that ``None`` is
+        stored as SQL ``NULL``. An instance is used as is, e.g. JSONB on PostgreSQL only::
+
+            JSON(none_as_null=True).with_variant(JSONB(none_as_null=True), "postgresql")
+        """
+        return cast("PydanticJSON[Self]", cls.as_mutable(PydanticJSON(cls, json_type)))

sqlalchemy_pydantic_json/alembic.py

@@ -0,0 +1,102 @@
+"""
+Alembic support: render `PydanticJSON` columns in migrations as their plain JSON type.
+
+Without this, autogenerate writes
+``sqlalchemy_pydantic_json._model.PydanticJSON(none_as_null=True)`` into the migration, which fails
+when it runs. With it, the migration gets ``sa.JSON(none_as_null=True)``, and depends on neither
+this package nor your models.
+
+In ``env.py``, pass the result of `make_render_item()` to ``context.configure()`` (in both the
+offline and the online function)::
+
+    from sqlalchemy_pydantic_json.alembic import make_render_item
+
+    context.configure(..., render_item=make_render_item())
+
+If you already have a ``render_item`` function of your own, let it handle everything else::
+
+    context.configure(..., render_item=make_render_item(wrap=my_render_item))
+
+This module doesn't import Alembic at runtime.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Literal, Never, cast
+
+from sqlalchemy_pydantic_json._model import PydanticJSON
+
+if TYPE_CHECKING:
+    from alembic.autogenerate.api import AutogenContext
+    from sqlalchemy.types import TypeEngine
+
+__all__ = ["make_render_item"]
+
+# the signature Alembic expects for ``render_item``
+_RenderItem = Callable[[str, Any, "AutogenContext"], "str | Literal[False]"]
+
+
+def _render_item(type_: str, obj: Any, autogen_context: AutogenContext) -> str | Literal[False]:
+    """
+    Render `PydanticJSON` column types as their underlying JSON type.
+
+    Returns ``False`` for everything else, which tells Alembic to use its default rendering.
+    """
+    if type_ != "type" or not isinstance(obj, PydanticJSON):
+        return False
+    impl = obj.impl_instance
+    # Alembic's own type rendering (private API): renders the JSON type exactly as if the column
+    # were declared with it directly, incl. dialect imports, JSONB's `astext_type` and
+    # `with_variant()`. Only used while generating migrations; tested in CI.
+    from alembic.autogenerate import render
+
+    repr_type = cast(
+        "Callable[[TypeEngine[Any], AutogenContext], str] | None", vars(render).get("_repr_type")
+    )
+    if repr_type is None:
+        warnings.warn(
+            "alembic.autogenerate.render._repr_type is not available in this Alembic version; "
+            "falling back to simple rendering. Check the generated migration.",
+            stacklevel=2,
+        )
+        return _simple_repr_type(impl, autogen_context)
+    return repr_type(impl, autogen_context)
+
+
+def _simple_repr_type(impl: TypeEngine[Any], autogen_context: AutogenContext) -> str:
+    """Fallback rendering; doesn't handle `with_variant()` or nested types like JSONB's."""
+    module = type(impl).__module__
+    if module.startswith("sqlalchemy.dialects."):
+        # e.g. sqlalchemy.dialects.postgresql.json -> postgresql.JSONB(...)
+        dialect = module.split(".")[2]
+        autogen_context.imports.add(f"from sqlalchemy.dialects import {dialect}")
+        return f"{dialect}.{impl!r}"
+    prefix = autogen_context.opts.get("sqlalchemy_module_prefix", "sa.") or ""
+    return f"{prefix}{impl!r}"
+
+
+def make_render_item(*args: Never, wrap: _RenderItem | None = None) -> _RenderItem:
+    """
+    Return a ``render_item`` function for Alembic's ``context.configure()``.
+
+    It renders `PydanticJSON` column types as their underlying JSON type. Everything else is passed
+    on to `wrap` if given, or otherwise left to Alembic's default rendering.
+    """
+    # `*args` only exists to give a clear error when the function itself is passed to Alembic
+    # (``render_item=make_render_item``), which then calls it with three positional arguments.
+    if args:  # ty: ignore[redundant-condition]  # only reachable when called untyped, by Alembic
+        raise TypeError(
+            "make_render_item() takes no positional arguments. Pass its result to Alembic: "
+            "context.configure(render_item=make_render_item()), or "
+            "make_render_item(wrap=my_render_item) to combine it with your own function."
+        )
+
+    def render_item(type_: str, obj: Any, autogen_context: AutogenContext) -> str | Literal[False]:
+        rendered = _render_item(type_, obj, autogen_context)
+        if rendered is not False or wrap is None:
+            return rendered
+        return wrap(type_, obj, autogen_context)
+
+    return render_item

sqlalchemy_pydantic_json-0.0.1a1.dist-info/METADATA

@@ -0,0 +1,376 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-pydantic-json
+Version: 0.0.1a1
+Summary: Pydantic v2 models in SQLAlchemy JSON columns with automatic mutation tracking
+Keywords: sqlalchemy,pydantic,json,jsonb,mutable,mutation-tracking,orm
+Author: Joakim Nordling
+Author-email: Joakim Nordling <joakim.nordling@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Dist: sqlalchemy>=2.0.14
+Requires-Dist: pydantic>=2.11
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/joakimnordling/sqlalchemy-pydantic-json
+Project-URL: Documentation, https://github.com/joakimnordling/sqlalchemy-pydantic-json#readme
+Project-URL: Changelog, https://github.com/joakimnordling/sqlalchemy-pydantic-json/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/joakimnordling/sqlalchemy-pydantic-json/issues
+Description-Content-Type: text/markdown
+
+# sqlalchemy-pydantic-json
+
+Store Pydantic models in SQLAlchemy JSON columns, and just change them in place: every change,
+however deeply nested, is saved when you commit.
+
+No `flag_modified()` calls, no event listeners in your code, and full type-checker support
+(mypy, pyright and ty).
+
+## Why
+
+A JSON column is a convenient place for structured data that doesn't deserve its own tables:
+settings, preferences, metadata. With plain SQLAlchemy you get dicts and lists back, and changing
+them in place isn't noticed: `user.settings["theme"] = "dark"` is silently lost unless you also call
+`flag_modified(user, "settings")`. SQLAlchemy's `MutableDict` helps for one level, but not for
+nested structures, and not for Pydantic models.
+
+This package gives you real Pydantic models in the column (validation, defaults, types,
+autocompletion) and tracks every change inside them: fields, lists, dicts, sets and nested models,
+however deep.
+
+## Installation
+
+```bash
+pip install sqlalchemy-pydantic-json
+# or
+uv add sqlalchemy-pydantic-json
+```
+
+Requires Python 3.11+, SQLAlchemy 2.0.14+ and Pydantic 2.11+. Tested with SQLite, PostgreSQL and
+MariaDB, with both `Session` and `AsyncSession`.
+
+**Using Alembic?** Then also do the [one-time Alembic setup](#alembic-setup) below. Without it,
+autogenerated migrations fail.
+
+## Quick start
+
+Use `EmbeddedPydanticModel` as the base class for the column's model **and for every model inside
+it**, and declare the column with `Model.column()`:
+
+```python
+from sqlalchemy import create_engine, select
+from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column
+
+from sqlalchemy_pydantic_json import EmbeddedPydanticModel
+
+
+class Visit(EmbeddedPydanticModel):
+    page: str = "/"
+
+
+class Address(EmbeddedPydanticModel):
+    city: str = "Helsinki"
+    lines: list[str] = []
+
+
+class Settings(EmbeddedPydanticModel):
+    theme: str = "light"
+    tags: set[str] = set()
+    address: Address = Address()
+    history: list[Visit] = []
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    settings: Mapped[Settings] = mapped_column(Settings.column(), default=Settings)
+    extra: Mapped[Settings | None] = mapped_column(Settings.column())  # nullable
+
+
+engine = create_engine("sqlite://")
+Base.metadata.create_all(engine)
+
+with Session(engine) as session:
+    session.add(User(id=1))
+    session.commit()
+
+    user = session.get(User, 1)
+    user.settings.theme = "dark"
+    user.settings.tags.add("admin")
+    user.settings.address.lines.append("Mannerheimintie 1")
+    user.settings.history.append(Visit(page="/home"))
+    user.settings.history[0].page = "/start"
+    assert user in session.dirty  # every change above marks the row as changed
+    session.commit()
+
+with Session(engine) as session:
+    user = session.get(User, 1)
+    assert user.settings.address.lines == ["Mannerheimintie 1"]
+    assert user.settings.history[0].page == "/start"
+```
+
+You can also assign a whole model, or a dict (it's validated into the model), or `None` for a
+nullable column:
+
+```python
+with Session(engine) as session:
+    user = session.get(User, 1)
+    user.settings = Settings(theme="blue")
+    user.extra = {"theme": "green"}
+    assert isinstance(user.extra, Settings)
+    user.extra = None  # stored as SQL NULL
+    session.commit()
+```
+
+## PostgreSQL: JSON or JSONB
+
+`Model.column()` uses SQLAlchemy's generic `JSON` type, which works on every database. On
+PostgreSQL that creates a `json` column. For `jsonb` (binary, indexable, more operators), pass
+`json_type`:
+
+<!-- readme-test: skip -->
+```python
+from sqlalchemy import JSON
+from sqlalchemy.dialects.postgresql import JSONB
+
+# always JSONB (PostgreSQL only)
+settings: Mapped[Settings] = mapped_column(Settings.column(json_type=JSONB), default=Settings)
+
+# JSONB on PostgreSQL, JSON elsewhere (e.g. SQLite in tests)
+settings: Mapped[Settings] = mapped_column(
+    Settings.column(
+        json_type=JSON(none_as_null=True).with_variant(JSONB(none_as_null=True), "postgresql")
+    ),
+    default=Settings,
+)
+```
+
+A type *class* such as `JSONB` automatically gets `none_as_null=True`, so that `None` is stored as
+SQL `NULL`. A type *instance* is used as is, so pass `none_as_null=True` yourself, as above.
+
+## Querying inside the JSON
+
+The column keeps SQLAlchemy's JSON operators, so you can filter on values inside the model:
+
+```python
+with Session(engine) as session:
+    blue = session.scalars(select(User).where(User.settings["theme"].as_string() == "blue")).all()
+    in_helsinki = session.scalars(
+        select(User).where(User.settings[("address", "city")].as_string() == "Helsinki")
+    ).all()
+    assert [u.id for u in blue] == [1]
+```
+
+See SQLAlchemy's [JSON type documentation](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.JSON)
+for the operators, and what each database supports.
+
+## Aliases (e.g. camelCase)
+
+Pydantic aliases decide the key names in the stored JSON. For camelCase, make your own base class
+with an alias generator, and use it for all of your models:
+
+```python
+from pydantic import ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class CamelModel(EmbeddedPydanticModel):
+    model_config = ConfigDict(alias_generator=to_camel, validate_by_name=True)
+
+
+class Profile(CamelModel):
+    display_name: str = "anon"  # stored as "displayName"
+    tax_id: str | None = Field(default=None, alias="TIN")  # an explicit alias wins: "TIN"
+
+
+class Member(Base):
+    __tablename__ = "members"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    profile: Mapped[Profile] = mapped_column(Profile.column(), default=Profile)
+
+
+Base.metadata.create_all(engine)
+
+with Session(engine) as session:
+    session.add(Member(id=1, profile=Profile(display_name="Jocke", TIN="123")))
+    session.commit()  # stored as {"displayName": "Jocke", "TIN": "123"}
+
+    query = select(Member.id).where(Member.profile["displayName"].as_string() == "Jocke")
+    assert session.scalars(query).all() == [1]
+```
+
+- The JSON is stored with the aliases, as by Pydantic's `model_dump(by_alias=True)`. Loading
+  accepts both the aliases and the field names, so rows stored before you added an alias still
+  load. They're stored with the aliases the next time they're saved.
+- Queries into the JSON use the stored names: `Member.profile["displayName"]`.
+- `validate_by_name=True` lets your Python code use field names. Type checkers know the field names
+  of generated aliases (`display_name=`), but only the alias of an explicit `Field(alias="TIN")`
+  (`TIN=`), so write it that way. Also pass `Field(default=...)` as a keyword: type checkers treat
+  a positional default as a required field.
+- A field must be loadable from the name it's stored under. If its `serialization_alias` differs
+  from its `validation_alias`, defining the model raises a `TypeError` (include the stored name
+  with `AliasChoices` if you need both).
+
+## Default values
+
+These all work:
+
+<!-- readme-test: skip -->
+```python
+# a new model for each row (recommended)
+settings: Mapped[Settings] = mapped_column(Settings.column(), default=Settings)
+
+# a dict, validated into a new model for each row
+settings: Mapped[Settings] = mapped_column(Settings.column(), default={"theme": "dark"})
+
+# a default in the database; the model's own field defaults fill in the rest when loaded
+settings: Mapped[Settings] = mapped_column(Settings.column(), server_default=text("'{}'"))
+```
+
+Don't use a model *instance* as the default (`default=Settings()`): SQLAlchemy then puts that same
+object into every new row, so changing one row's settings changes all of them.
+
+## Alembic setup
+
+Alembic's autogenerate can't write the column type into a migration by itself: it would write
+`sqlalchemy_pydantic_json._model.PydanticJSON(...)`, which fails when the migration runs. Tell it to
+write the plain JSON type instead. In your `env.py`, pass `render_item` to **both**
+`context.configure()` calls (offline and online):
+
+<!-- readme-test: skip -->
+```python
+from sqlalchemy_pydantic_json.alembic import make_render_item
+
+context.configure(
+    ...,
+    render_item=make_render_item(),
+)
+```
+
+If you already have a `render_item` function of your own, wrap it:
+
+<!-- readme-test: skip -->
+```python
+context.configure(..., render_item=make_render_item(wrap=my_render_item))
+```
+
+Migrations then contain `sa.JSON(none_as_null=True)` (or `postgresql.JSONB(...)`, or the variant),
+and depend on neither this package nor your models, so they keep working as your models change.
+
+Changing the *model* doesn't change the database schema, so Alembic has nothing to generate for
+it. Existing rows must still validate against the new model, though: after adding a required field
+or renaming one, say, either make the model accept the old data, or update the stored JSON yourself
+(for example in a hand-written data migration). Changing the column's type between JSON and JSONB
+is detected like any other type change.
+
+## Using with SQLModel
+
+Declare the column with `sa_column`:
+
+```python
+from sqlalchemy import Column
+from sqlmodel import Field, SQLModel, col, select
+from sqlmodel import Session as SQLModelSession
+
+
+class Player(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    settings: Settings = Field(
+        default_factory=Settings,
+        sa_column=Column(Settings.column(), nullable=False),
+    )
+
+
+SQLModel.metadata.create_all(engine)
+
+with SQLModelSession(engine) as session:
+    session.add(Player(id=1))
+    session.commit()
+
+    player = session.get(Player, 1)
+    player.settings.tags.add("captain")  # tracked, as with SQLAlchemy models
+    assert player in session.dirty
+    session.commit()
+
+    query = select(Player.id).where(col(Player.settings)["theme"].as_string() == "light")
+    assert session.exec(query).all() == [1]
+```
+
+## Rules and gotchas
+
+- **Every model inside the column should inherit `EmbeddedPydanticModel`,** not
+  `pydantic.BaseModel`. A plain `BaseModel` still loads and saves correctly, and replacing it as a
+  whole is tracked, but changes *inside* it aren't: they're lost unless something else in the row
+  changes too. So plain models are fine only if they're never changed in place, for example frozen
+  ones (`model_config = ConfigDict(frozen=True)`).
+- **Values are validated every time a row is loaded,** against the current model. When you change
+  a model, existing rows must still validate: give new fields a default (or update the stored
+  rows), and handle renamed or removed fields, for example with a `model_validator(mode="before")`
+  or a hand-written data migration.
+- **Bulk and Core statements bypass tracking,** as with any SQLAlchemy attribute:
+  `session.execute(update(User).values(...))` writes what you give it, and doesn't know about
+  in-place changes.
+- **Values you keep across an expiring commit are no longer tracked.** With the default
+  `expire_on_commit=True`, `commit()` expires the row; the next access loads a fresh model. Changing
+  the old model you kept a reference to does nothing (and doesn't raise). Read the value from the row
+  again after committing.
+- **Shallow copies share nested models,** as in Pydantic: changing a nested model in a
+  `model_copy()` or `copy.copy()` also changes it in the original. Use `model_copy(deep=True)` or
+  `copy.deepcopy()` for an independent copy. Copies (and pickled models) aren't attached to any row
+  until you assign them.
+- **Thread safety** is the same as for SQLAlchemy sessions: don't share one between threads.
+
+## How it works
+
+- `PydanticJSON` is a SQLAlchemy `TypeDecorator` over `JSON`: it validates the model on load and
+  dumps it with `model_dump(mode="json")` on save. On its own it doesn't track anything.
+- `EmbeddedPydanticModel` combines Pydantic's `BaseModel` with SQLAlchemy's `Mutable`, and
+  `Model.column()` is `Model.as_mutable(PydanticJSON(Model))`.
+- Whenever a field is set, lists, dicts and sets are wrapped in tracked versions of SQLAlchemy's
+  `MutableList`, `MutableDict` and `MutableSet`, and nested models are linked to their parent.
+- Each model or container keeps weak references to all of its parents. A change is passed up from
+  parent to parent until it reaches the model in the column, which marks the row as changed. A
+  parent that no longer holds the value (after a `pop()` or reassignment, say) is skipped and
+  forgotten, so values can be moved around and shared freely.
+
+## Alternatives
+
+- [sqlalchemy-json](https://github.com/edelooff/sqlalchemy-json): nested change tracking for plain
+  dicts and lists, without Pydantic models.
+- [SQLAlchemy-Nested-Mutable](https://github.com/wonderbeyond/sqlalchemy-nested-mutable): nested
+  tracking including Pydantic models, but for Pydantic v1 only.
+- [SQLModel](https://sqlmodel.tiangolo.com/): Pydantic and SQLAlchemy in one model class, but no
+  built-in change tracking for Pydantic models in JSON columns. This package adds it
+  ([see above](#using-with-sqlmodel)).
+- [activemodel](https://github.com/iloveitaly/activemodel): an ActiveRecord-style framework on top
+  of SQLModel. Its `PydanticJSONMixin` also tracks changes in Pydantic models in JSON columns, by
+  comparing snapshots of the JSON when the session commits. It requires SQLModel, and a change
+  isn't visible to flushes (including autoflush before a query) until then.
+
+This package needs only SQLAlchemy 2.0 and Pydantic. It works with SQLAlchemy's declarative models
+and with SQLModel, and notices every change the moment it's made.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/joakimnordling/sqlalchemy-pydantic-json/blob/main/CONTRIBUTING.md).
+Changes are listed in the [changelog](https://github.com/joakimnordling/sqlalchemy-pydantic-json/blob/main/CHANGELOG.md).
+
+## License
+
+[MIT](https://github.com/joakimnordling/sqlalchemy-pydantic-json/blob/main/LICENSE)

sqlalchemy_pydantic_json-0.0.1a1.dist-info/RECORD

@@ -0,0 +1,8 @@
+sqlalchemy_pydantic_json/__init__.py,sha256=tMX1uWNicv4g0PZUjL82Vs2ItuTC5gu8MMtDtEaZ36I,226
+sqlalchemy_pydantic_json/_model.py,sha256=xW3u2X6iqDmK71LTCM1VI7_sokt7Dq7kyXO0lLEeiDs,14661
+sqlalchemy_pydantic_json/alembic.py,sha256=_6l6jOYJjPTGyDkH9Nybm0n634R3WXRO1G5Mu7BHRZ8,4360
+sqlalchemy_pydantic_json/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlalchemy_pydantic_json-0.0.1a1.dist-info/licenses/LICENSE,sha256=NO_zyIgDivri9_xYthj7rkpolyvSNXPpUBBu56uIRGY,1072
+sqlalchemy_pydantic_json-0.0.1a1.dist-info/WHEEL,sha256=R1d3uUTbmXM1FHXH_itQashbrqrOSVj-hvBCpmkIIGE,81
+sqlalchemy_pydantic_json-0.0.1a1.dist-info/METADATA,sha256=gi5e3-IRC3nP3CTXtpuWr9cN3akc3CgeTx2KvX8ivWM,15274
+sqlalchemy_pydantic_json-0.0.1a1.dist-info/RECORD,,

sqlalchemy_pydantic_json-0.0.1a1.dist-info/WHEEL

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

sqlalchemy_pydantic_json-0.0.1a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joakim Nordling
+
+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.