Add `sqlalchemy.ext.index` for indexed attributes for ORM

Add `sqlalchemy.ext.index.index_property`
which subscribe an index of a column with `Indexable` type.

Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com>
Change-Id: I238c23131e4fded5dc7f7a25eb02e26008099d00
Pull-request: https://github.com/zzzeek/sqlalchemy/pull/235

4 files changed, 49 insertions, 1 deletions

diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index 662bad00a..7194ac116 100644
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -22,6 +22,18 @@
     :version: 1.1.0b1
 
     .. change::
+        :tags: feature, orm, ext
+
+        A new ORM extension :ref:`indexable_toplevel` is added, which allows
+        construction of Python attributes which refer to specific elements
+        of "indexed" structures such as arrays and JSON fields.  Pull request
+        courtesy Jeong YunWon.
+
+        .. seealso::
+
+            :ref:`feature_indexable`
+
+    .. change::
         :tags: bug, sql
         :tickets: 3724
 
diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst
index ea932b509..766b06f2e 100644
--- a/doc/build/changelog/migration_11.rst
+++ b/doc/build/changelog/migration_11.rst
@@ -258,6 +258,40 @@ relationship attribute to an object, which is handled distinctly::
 
 :ticket:`3321`
 
+.. _feature_indexable:
+
+New Indexable ORM extension
+---------------------------
+
+The :ref:`indexable_toplevel` extension is an extension to the hybrid
+attribute feature which allows the construction of attributes which
+refer to specific elements of an "indexable" data type, such as an array
+or JSON field::
+
+    class Person(Base):
+        __tablename__ = 'person'
+
+        id = Column(Integer, primary_key=True)
+        data = Column(JSON)
+
+        name = index_property('data', 'name')
+
+Above, the ``name`` attribute will read/write the field ``"name"``
+from the JSON column ``data``, after initializing it to an
+empty dictionary::
+
+    >>> person = Person(name='foobar')
+    >>> person.name
+    foobar
+
+The extension also triggers a change event when the attribute is modified,
+so that there's no need to use :class:`~.mutable.MutableDict` in order
+to track this change.
+
+.. seealso::
+
+    :ref:`indexable_toplevel`
+
 .. _change_3250:
 
 New options allowing explicit persistence of NULL over a default
diff --git a/doc/build/index.rst b/doc/build/index.rst
index a28dfca82..377ccfb41 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -38,7 +38,8 @@ of Python objects, proceed first to the tutorial.
   :doc:`Association Proxy <orm/extensions/associationproxy>` |
   :doc:`Hybrid Attributes <orm/extensions/hybrid>` |
   :doc:`Automap <orm/extensions/automap>` |
-  :doc:`Mutable Scalars <orm/extensions/mutable>`
+  :doc:`Mutable Scalars <orm/extensions/mutable>` |
+  :doc:`Indexable <orm/extensions/indexable>`
 
 * **ORM Usage:**
   :doc:`Session Usage and Guidelines <orm/session>` |
diff --git a/doc/build/orm/extensions/index.rst b/doc/build/orm/extensions/index.rst
index 091ceb40a..e23fd55ee 100644
--- a/doc/build/orm/extensions/index.rst
+++ b/doc/build/orm/extensions/index.rst
@@ -23,5 +23,6 @@ behavior.   In particular the "Horizontal Sharding", "Hybrid Attributes", and
     orderinglist
     horizontal_shard
     hybrid
+    indexable
     instrumentation