Merge "Ensure custom ops have consistent typing behavior, boolean support"

4 files changed, 87 insertions, 6 deletions

diff --git a/doc/build/changelog/migration_12.rst b/doc/build/changelog/migration_12.rst
index 36b2819fa..4cfaf38c4 100644
--- a/doc/build/changelog/migration_12.rst
+++ b/doc/build/changelog/migration_12.rst
@@ -1207,6 +1207,56 @@ The reason post_update emits an UPDATE even for an UPDATE is now discussed at
 Key Behavioral Changes - Core
 =============================
 
+.. _change_4063:
+
+The typing behavior of custom operators has been made consistent
+----------------------------------------------------------------
+
+User defined operators can be made on the fly using the
+:meth:`.Operators.op` function.   Previously, the typing behavior of
+an expression against such an operator was inconsistent and also not
+controllable.
+
+Whereas in 1.1, an expression such as the following would produce
+a result with no return type (assume ``-%>`` is some special operator
+supported by the database)::
+
+    >>> column('x', types.DateTime).op('-%>')(None).type
+    NullType()
+
+Other types would use the default behavior of using the left-hand type
+as the return type::
+
+    >>> column('x', types.String(50)).op('-%>')(None).type
+    String(length=50)
+
+These behaviors were mostly by accident, so the behavior has been made
+consistent with the second form, that is the default return type is the
+same as the left-hand expression::
+
+    >>> column('x', types.DateTime).op('-%>')(None).type
+    DateTime()
+
+As most user-defined operators tend to be "comparison" operators, often
+one of the many special operators defined by Postgresql, the
+:paramref:`.Operators.op.is_comparison` flag has been repaired to follow
+its documented behavior of allowing the return type to be :class:`.Boolean`
+in all cases, including for :class:`.ARRAY` and :class:`.JSON`::
+
+    >>> column('x', types.String(50)).op('-%>', is_comparison=True)(None).type
+    Boolean()
+    >>> column('x', types.ARRAY(types.Integer)).op('-%>', is_comparison=True)(None).type
+    Boolean()
+    >>> column('x', types.JSON()).op('-%>', is_comparison=True)(None).type
+    Boolean()
+
+To assist with boolean comparison operators, a new shorthand method
+:meth:`.Operators.bool_op` has been added.    This method should be preferred
+for on-the-fly boolean operators::
+
+    >>> print(column('x', types.Integer).bool_op('-%>')(5))
+    x -%> :x_1
+
 
 .. _change_3785:
 
diff --git a/doc/build/changelog/unreleased_12/4063.rst b/doc/build/changelog/unreleased_12/4063.rst
new file mode 100644
index 000000000..2d79961ee
--- /dev/null
+++ b/doc/build/changelog/unreleased_12/4063.rst
@@ -0,0 +1,16 @@
+.. change::
+    :tags: bug, sql
+    :tickets: 4063
+
+    Refined the behavior of :meth:`.Operators.op` such that in all cases,
+    if the :paramref:`.Operators.op.is_comparison` flag is set to True,
+    the return type of the resulting expression will be
+    :class:`.Boolean`, and if the flag is False, the return type of the
+    resulting expression will be the same type as that of the left-hand
+    expression, which is the typical default behavior of other operators.
+    Also added a new parameter :paramref:`.Operators.op.return_type` as well
+    as a helper method :meth:`.Operators.bool_op`.
+
+    .. seealso::
+
+        :ref:`change_4063`
\ No newline at end of file
diff --git a/doc/build/core/custom_types.rst b/doc/build/core/custom_types.rst
index 64f91b23f..5384d0fd4 100644
--- a/doc/build/core/custom_types.rst
+++ b/doc/build/core/custom_types.rst
@@ -513,6 +513,15 @@ expression object produces a new SQL expression construct. Above, we
 could just as well have said ``self.expr.op("goofy")(other)`` instead
 of ``self.op("goofy")(other)``.
 
+When using :meth:`.Operators.op` for comparison operations that return a
+boolean result, the :paramref:`.Operators.op.is_comparison` flag should be
+set to ``True``::
+
+    class MyInt(Integer):
+        class comparator_factory(Integer.Comparator):
+            def is_frobnozzled(self, other):
+                return self.op("--is_frobnozzled->", is_comparison=True)(other)
+
 New methods added to a :class:`.TypeEngine.Comparator` are exposed on an
 owning SQL expression
 using a ``__getattr__`` scheme, which exposes methods added to
@@ -532,7 +541,6 @@ Using the above type::
     >>> print(sometable.c.data.log(5))
     log(:log_1, :log_2)
 
-
 Unary operations
 are also possible.  For example, to add an implementation of the
 PostgreSQL factorial operator, we combine the :class:`.UnaryExpression` construct
@@ -555,12 +563,12 @@ Using the above type::
     >>> print(column('x', MyInteger).factorial())
     x !
 
-See also:
+.. seealso::
+
+    :meth:`.Operators.op`
 
-:attr:`.TypeEngine.comparator_factory`
+    :attr:`.TypeEngine.comparator_factory`
 
-.. versionadded:: 0.8  The expression system was enhanced to support
-  customization of operators on a per-type level.
 
 
 Creating New Types
diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index 432066980..b8a362daa 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -640,10 +640,17 @@ normally expected, using :func:`.type_coerce`::
     stmt = select([expr])
 
 
+For boolean operators, use the :meth:`.Operators.bool_op` method, which
+will ensure that the return type of the expression is handled as boolean::
+
+    somecolumn.bool_op('-->')('some value')
+
+.. versionadded:: 1.2.0b3  Added the :meth:`.Operators.bool_op` method.
+
 Operator Customization
 ----------------------
 
-While :meth:`.ColumnOperators.op` is handy to get at a custom operator in a hurry,
+While :meth:`.Operators.op` is handy to get at a custom operator in a hurry,
 the Core supports fundamental customization and extension of the operator system at
 the type level.   The behavior of existing operators can be modified on a per-type
 basis, and new operations can be defined which become available for all column