[Sqlalchemy-tickets] [sqlalchemy] #2803: HSTORE docs fix

[sqlalchemy <mi...@zz...>]

#2803: HSTORE docs fix
---------------------------+-----------------------------------------
 Reporter:  jonathan       |           Owner:  zzzeek
     Type:  defect         |          Status:  new
 Priority:  medium         |       Milestone:
Component:  documentation  |        Severity:  no triage selected yet
 Keywords:                 |  Progress State:  awaiting triage
---------------------------+-----------------------------------------
 The HSTORE docs are confusing:

 > For usage with the SQLAlchemy ORM, it may be desirable to combine the
 usage of HSTORE withMutableDict dictionary now part of the
 sqlalchemy.ext.mutable extension. This extension will allow in-place
 changes to dictionary values to be detected by the unit of work:

 It's not really "desirable" -- it's pretty much required for most write
 operations. ;)

 The wording states this is needed for "changes to dictionary values".
 That's misleading -- as it suggests a change to an existing key/value
 pair.  The extension is required for any changes to the dictionary itself
 -- be updating a k/v pair or adding a k/v pair.  You can only replace the
 entire attribute with a new dict in order to update without the
 MutableDict extension.

 If you add a new k/v pair, inspecting the attribute shows a new value for
 the k/v, however the SQL is not emmitted unless the MutableDict extension
 is activated for the column.

 It makes perfect sense what is going on and why.  The docs should just be
 changed to something like...

 {{{
 - This extension will allow in-place changes to dictionary values to be
 detected by the unit of work:
 + This extension will allow changes to the attribute's dictionary to be
 detected by the unit of work:
 }}}

 or

 {{{
 - This extension will allow in-place changes to dictionary values to be
 detected by the unit of work:
 + This extension will allow changes to an existing dictionary ( such as
 adding a new key/value pair or updating an existing one) to be detected by
 the unit of work:
 }}}

--
Ticket URL: <http://www.sqlalchemy.org/trac/ticket/2803>
sqlalchemy <http://www.sqlalchemy.org/>
The Database Toolkit for Python