repair any_() / all_() "implicit flip" behavior for None

Fixed an inconsistency in the any_() / all_() functions / methods where the
special behavior these functions have of "flipping" the expression such
that the "ANY" / "ALL" expression is always on the right side would not
function if the comparison were against the None value, that is,
"column.any_() == None" should produce the same SQL expression as "null()
== column.any_()". Added more docs to clarify this as well, plus mentions
that any_() / all_() generally supersede the ARRAY version "any()" /
"all()".

Fixes: #7140
Change-Id: Ia5d55414ba40eb3fbda3598931fdd24c9b4a4411

1 files changed, 14 insertions, 29 deletions

diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index 771de1e47..695e086b8 100644
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -1161,24 +1161,16 @@ class ColumnOperators(Operators):
         return self.operate(distinct_op)
 
     def any_(self):
-        """Produce a :func:`_expression.any_` clause against the
+        """Produce an :func:`_expression.any_` clause against the
         parent object.
 
-        This operator is only appropriate against a scalar subquery
-        object, or for some backends an column expression that is
-        against the ARRAY type, e.g.::
+        See the documentation for :func:`_sql.any_` for examples.
 
-            # postgresql '5 = ANY (somearray)'
-            expr = 5 == mytable.c.somearray.any_()
-
-            # mysql '5 = ANY (SELECT value FROM table)'
-            expr = 5 == select(table.c.value).scalar_subquery().any_()
-
-        .. seealso::
-
-            :func:`_expression.any_` - standalone version
-
-            :func:`_expression.all_` - ALL operator
+        .. note:: be sure to not confuse the newer
+            :meth:`_sql.ColumnOperators.any_` method with its older
+            :class:`_types.ARRAY`-specific counterpart, the
+            :meth:`_types.ARRAY.Comparator.any` method, which a different
+            calling syntax and usage pattern.
 
         .. versionadded:: 1.1
 
@@ -1186,24 +1178,17 @@ class ColumnOperators(Operators):
         return self.operate(any_op)
 
     def all_(self):
-        """Produce a :func:`_expression.all_` clause against the
+        """Produce an :func:`_expression.all_` clause against the
         parent object.
 
-        This operator is only appropriate against a scalar subquery
-        object, or for some backends an column expression that is
-        against the ARRAY type, e.g.::
-
-            # postgresql '5 = ALL (somearray)'
-            expr = 5 == mytable.c.somearray.all_()
-
-            # mysql '5 = ALL (SELECT value FROM table)'
-            expr = 5 == select(table.c.value).scalar_subquery().all_()
-
-        .. seealso::
+        See the documentation for :func:`_sql.all_` for examples.
 
-            :func:`_expression.all_` - standalone version
+        .. note:: be sure to not confuse the newer
+            :meth:`_sql.ColumnOperators.all_` method with its older
+            :class:`_types.ARRAY`-specific counterpart, the
+            :meth:`_types.ARRAY.Comparator.all` method, which a different
+            calling syntax and usage pattern.
 
-            :func:`_expression.any_` - ANY operator
 
         .. versionadded:: 1.1