From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 28 Oct 2015 15:22:55 +0000 (-0400)
Subject: - add a JSON warning for coerce_compared_value
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=763b40fca779a48e6c8b0888d323550de3669593;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add a JSON warning for coerce_compared_value

(cherry picked from commit 98c1dcc6bcade313a254fe11e8efa3c5b5ad959e)
---

diff --git a/lib/sqlalchemy/sql/type_api.py b/lib/sqlalchemy/sql/type_api.py
index 719f013768..3b157d419f 100644
--- a/lib/sqlalchemy/sql/type_api.py
+++ b/lib/sqlalchemy/sql/type_api.py
@@ -566,6 +566,26 @@ class TypeDecorator(TypeEngine):
             else:
                 return self
 
+    .. warning::
+
+       Note that the **behavior of coerce_compared_value is not inherited
+       by default from that of the base type**.
+       If the :class:`.TypeDecorator` is augmenting a
+       type that requires special logic for certain types of operators,
+       this method **must** be overridden.  A key example is when decorating
+       the :class:`.postgresql.JSON` and :class:`.postgresql.JSONB` types;
+       the default rules of :meth:`.TypeEngine.coerce_compared_value` should
+       be used in order to deal with operators like index operations::
+
+            class MyJsonType(TypeDecorator):
+                impl = postgresql.JSON
+
+                def coerce_compared_value(self, op, value):
+                    return self.impl.coerce_compared_value(op, value)
+
+       Without the above step, index operations such as ``mycol['foo']``
+       will cause the index value ``'foo'`` to be JSON encoded.
+
     """
 
     __visit_name__ = "type_decorator"