feat: support list in non-nested mutable json

README.rst

@@ -21,6 +21,20 @@ This is essentially the SQLAlchemy `mutable JSON recipe`_. We define a simple au
         name = Column(Text)
         handles = Column(MutableJson)
 
+Or, using the declarative mapping style:
+
+.. code-block:: python
+
+    class Category(Base):
+        __tablename__ = "categories"
+
+        id = mapped_column(Integer, primary_key=True)
+        created_at: Mapped[DateTime] = mapped_column(DateTime, default=datetime.now)
+        updated_at: Mapped[DateTime] = mapped_column(
+            DateTime, default=datetime.now, onupdate=datetime.now
+        )
+        keywords: Mapped[list[str]] = mapped_column(MutableJson)
+
 The example below loads one of the existing authors and retrieves the mapping of social media handles. The error in the twitter handle is then corrected and committed. The change is detected by SQLAlchemy and the appropriate ``UPDATE`` statement is generated.
 
 .. code-block:: python

sqlalchemy_json/__init__.py

@@ -1,4 +1,4 @@
-from sqlalchemy.ext.mutable import Mutable, MutableDict
+from sqlalchemy.ext.mutable import Mutable, MutableDict, MutableList
 from sqlalchemy.types import JSON
 
 from .track import TrackedDict, TrackedList
@@ -51,13 +51,28 @@ def coerce(cls, key, value):
         return super(cls).coerce(key, value)
 
 
+class MutableListOrDict(Mutable):
+    """SQLAlchemy `mutable` extension with change tracking for a single-depth list or dict."""
+
+    @classmethod
+    def coerce(cls, key, value):
+        if value is None:
+            return value
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, dict):
+            return MutableDict.coerce(key, value)
+        if isinstance(value, list):
+            return MutableList.coerce(key, value)
+        return super(cls).coerce(key, value)
+
 def mutable_json_type(dbtype=JSON, nested=False):
     """Type creator for (optionally nested) mutable JSON column types.
 
     The default backend data type is sqlalchemy.types.JSON, but can be set to
     any other type by providing the `dbtype` parameter.
     """
-    mutable_type = NestedMutable if nested else MutableDict
+    mutable_type = NestedMutable if nested else MutableListOrDict
     return mutable_type.as_mutable(dbtype)
 
 

test/test_sqlalchemy_json.py

@@ -67,6 +67,19 @@ def author(session):
     assert author.handles["twitter"] == "@JohnDoe"
     return author
 
+@pytest.fixture
+def author_with_list(session):
+    author = Author(
+        name="John Doe",
+        handles=["@JohnDoe", "JohnDoe"],
+    )
+    session.add(author)
+    session.commit()
+    session.refresh(author)
+
+    assert author.name == "John Doe"
+    assert author.handles == ["@JohnDoe", "JohnDoe"]
+    return author
 
 @pytest.fixture
 def article(session, author):
@@ -156,3 +169,10 @@ def test_dict_merging(session, article):
             "someone/somerepo": 10,
         },
     }
+
+def test_mutable_json_list(session, author_with_list):
+    author_with_list.handles.append("@mike_bianco")
+    session.commit()
+
+    assert author_with_list.handles == ["@JohnDoe", "JohnDoe", "@mike_bianco"]
+