[Sqlalchemy-tickets] [sqlalchemy] #2803: HSTORE docs fix
Brought to you by:
zzzeek
|
From: sqlalchemy <mi...@zz...> - 2013-08-15 19:40:32
|
#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
|