test / document postgresql_ops against a labeled expression

Since postgresql_ops explicitly states that it expects
string keys, to apply to a function call or expression one
needs to give the SQL expression a label that can be referred
to by name in the dictionary.   test / document this.

Change-Id: I4bc4ade46dac27f9c1b92e7823433292beab97b9
Fixes: #3970

1 files changed, 19 insertions, 8 deletions

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index 802c6a905..b9c15ca2d 100644
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -566,20 +566,31 @@ http://www.postgresql.org/docs/8.3/interactive/indexes-opclass.html).
 The :class:`.Index` construct allows these to be specified via the
 ``postgresql_ops`` keyword argument::
 
-    Index('my_index', my_table.c.id, my_table.c.data,
-                            postgresql_ops={
-                                'data': 'text_pattern_ops',
-                                'id': 'int4_ops'
-                            })
-
-.. versionadded:: 0.7.2
-    ``postgresql_ops`` keyword argument to :class:`.Index` construct.
+    Index(
+        'my_index', my_table.c.id, my_table.c.data,
+        postgresql_ops={
+            'data': 'text_pattern_ops',
+            'id': 'int4_ops'
+        })
 
 Note that the keys in the ``postgresql_ops`` dictionary are the "key" name of
 the :class:`.Column`, i.e. the name used to access it from the ``.c``
 collection of :class:`.Table`, which can be configured to be different than
 the actual name of the column as expressed in the database.
 
+If ``postgresql_ops`` is to be used against a complex SQL expression such
+as a function call, then to apply to the column it must be given a label
+that is identified in the dictionary by name, e.g.::
+
+    Index(
+        'my_index', my_table.c.id,
+        func.lower(my_table.c.data).label('data_lower'),
+        postgresql_ops={
+            'data_lower': 'text_pattern_ops',
+            'id': 'int4_ops'
+        })
+
+
 Index Types
 ^^^^^^^^^^^^