From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 18 Oct 2013 23:34:58 +0000 (-0400)
Subject: - attempt to clarify what mutable extension does for HSTORE, [ticket:2803]
X-Git-Tag: rel_0_8_3~6
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bb6df3f45f0d06e0b364ea06cb9e17c04513e192;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- attempt to clarify what mutable extension does for HSTORE, [ticket:2803]
---

diff --git a/lib/sqlalchemy/dialects/postgresql/hstore.py b/lib/sqlalchemy/dialects/postgresql/hstore.py
index dc9f05a604..f3df56489a 100644
--- a/lib/sqlalchemy/dialects/postgresql/hstore.py
+++ b/lib/sqlalchemy/dialects/postgresql/hstore.py
@@ -144,8 +144,10 @@ class HSTORE(sqltypes.Concatenable, sqltypes.TypeEngine):
     For usage with the SQLAlchemy ORM, it may be desirable to combine
     the usage of :class:`.HSTORE` with :class:`.MutableDict` dictionary
     now part of the :mod:`sqlalchemy.ext.mutable`
-    extension.  This extension will allow in-place changes to dictionary
-    values to be detected by the unit of work::
+    extension.  This extension will allow "in-place" changes to the
+    dictionary, e.g. addition of new keys or replacement/removal of existing
+    keys to/from the current dictionary, to produce events which will be detected
+    by the unit of work::
 
         from sqlalchemy.ext.mutable import MutableDict
 
@@ -163,6 +165,11 @@ class HSTORE(sqltypes.Concatenable, sqltypes.TypeEngine):
 
         session.commit()
 
+    When the :mod:`sqlalchemy.ext.mutable` extension is not used, the ORM
+    will not be alerted to any changes to the contents of an existing dictionary,
+    unless that dictionary value is re-assigned to the HSTORE-attribute itself,
+    thus generating a change event.
+
     .. versionadded:: 0.8
 
     .. seealso::