Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

JSON type with nested change tracking for SQLAlchemy

Project Description

SQLAlchemy-JSON provides mutation-tracked JSON types to SQLAlchemy:

  • MutableJson is a straightforward implementation for keeping track of top-level changes to JSON objects;
  • NestedMutableJson is an extension of this which tracks changes even when these happen in nested objects or arrays (Python dicts and lists).


Basic change tracking

This is essentially the SQLAlchemy mutable JSON recipe. We define a simple author model which list the author’s name and a property handles for various social media handles used:

class Author(Base):
    name = Column(Text)
    handles = 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.

>>> author = session.query(Author).first()
>>> author.handles
{'twitter': '@JohnDoe', 'facebook': 'JohnDoe'}
>>> author.handles['twitter'] = '@JDoe'
>>> session.commit()
>>> author.handles
{'twitter': '@JDoe', 'facebook': 'JohnDoe'}

Nested change tracking

The example below defines a simple model for articles. One of the properties on this model is a mutable JSON structure called references which includes a count of links that the article contains, grouped by domain:

class Article(Base):
    author = Column(ForeignKey(''))
    content = Column(Text)
    references = Column(NestedMutableJson)

With this in place, an existing article is loaded and its current references inspected. Following that, the count for one of these is increased by ten, and the session is committed:

>>> article = session.query(Article).first()
>>> article.references
{'': {'edelooff/sqlalchemy-json': 4, 'zzzeek/sqlalchemy': 7}}
>>> article.references['']['edelooff/sqlalchemy-json'] += 10
>>> session.commit()
>>> article.references
{'': {'edelooff/sqlalchemy-json': 14, 'zzzeek/sqlalchemy': 7}}

Had the articles model used MutableJson like in the previous example this code would have failed. This is because the top level dictionary is never altered directly. The nested mutable ensures the change happening at the lower level bubbles up to the outermost container.


  • SQLAlchemy-utils for its existing and database-engine specific choice of either native or simulated JSON type;
  • six to support both Python 2 and 3.



  • Fixes a typo in the README found after uploading 0.2.0 to PyPI.

0.2.0 (unreleased)

  • Now uses JSONType provided by SQLAlchemy-utils to handle backend storage;
  • Backwards incompatible: Changed class name JsonObject to MutableJson and NestedJsonObject to NestedMutableJson
  • Outermost container for NestedMutableJson can now be an array (Python list)

0.1.0 (unreleased)

Initial version. This initially carried a 1.0.0 version number but has never been released on PyPI.

Release History

Release History

This version
History Node


Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
sqlalchemy_json-0.2.1-py2.py3-none-any.whl (7.6 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Sep 11, 2017
sqlalchemy-json-0.2.1.tar.gz (4.9 kB) Copy SHA256 Checksum SHA256 Source Sep 11, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting