Rename Core expression isnot, not_in_

Several operators are renamed to achieve more consistent naming across
SQLAlchemy.

The operator changes are:

* `isnot` is now `is_not`
* `not_in_` is now `not_in`

Because these are core operators, the internal migration strategy for this
change is to support legacy terms for an extended period of time -- if not
indefinitely -- but update all documentation, tutorials, and internal usage
to the new terms.  The new terms are used to define the functions, and
the legacy terms have been deprecated into aliases of the new terms.

Fixes: #5429
Change-Id: Ia1e66e7a50ac35d3f6260d8bf6ba3ce8087cbad2

3 files changed, 44 insertions, 21 deletions

diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index ec1a57935..925441539 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -190,12 +190,12 @@ OPERATORS = {
     operators.match_op: " MATCH ",
     operators.notmatch_op: " NOT MATCH ",
     operators.in_op: " IN ",
-    operators.notin_op: " NOT IN ",
+    operators.not_in_op: " NOT IN ",
     operators.comma_op: ", ",
     operators.from_: " FROM ",
     operators.as_: " AS ",
     operators.is_: " IS ",
-    operators.isnot: " IS NOT ",
+    operators.is_not: " IS NOT ",
     operators.collate: " COLLATE ",
     # unary
     operators.exists: "EXISTS ",
diff --git a/lib/sqlalchemy/sql/default_comparator.py b/lib/sqlalchemy/sql/default_comparator.py
index eec174e8b..d5762ff1f 100644
--- a/lib/sqlalchemy/sql/default_comparator.py
+++ b/lib/sqlalchemy/sql/default_comparator.py
@@ -73,20 +73,20 @@ def _boolean_compare(
                     expr,
                     coercions.expect(roles.ConstExprRole, obj),
                     operators.is_,
-                    negate=operators.isnot,
+                    negate=operators.is_not,
                     type_=result_type,
                 )
-            elif op in (operators.ne, operators.isnot):
+            elif op in (operators.ne, operators.is_not):
                 return BinaryExpression(
                     expr,
                     coercions.expect(roles.ConstExprRole, obj),
-                    operators.isnot,
+                    operators.is_not,
                     negate=operators.is_,
                     type_=result_type,
                 )
             else:
                 raise exc.ArgumentError(
-                    "Only '=', '!=', 'is_()', 'isnot()', "
+                    "Only '=', '!=', 'is_()', 'is_not()', "
                     "'is_distinct_from()', 'isnot_distinct_from()' "
                     "operators can be used with None/True/False"
                 )
@@ -328,10 +328,10 @@ operator_lookup = {
     "asc_op": (_scalar, UnaryExpression._create_asc),
     "nullsfirst_op": (_scalar, UnaryExpression._create_nullsfirst),
     "nullslast_op": (_scalar, UnaryExpression._create_nullslast),
-    "in_op": (_in_impl, operators.notin_op),
-    "notin_op": (_in_impl, operators.in_op),
+    "in_op": (_in_impl, operators.not_in_op),
+    "not_in_op": (_in_impl, operators.in_op),
     "is_": (_boolean_compare, operators.is_),
-    "isnot": (_boolean_compare, operators.isnot),
+    "is_not": (_boolean_compare, operators.is_not),
     "collate": (_collate_impl,),
     "match_op": (_match_impl,),
     "notmatch_op": (_match_impl,),
diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index ba03a6934..5f5052c28 100644
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -596,7 +596,7 @@ class ColumnOperators(Operators):
         """
         return self.operate(in_op, other)
 
-    def notin_(self, other):
+    def not_in(self, other):
         """implement the ``NOT IN`` operator.
 
         This is equivalent to using negation with
@@ -608,8 +608,12 @@ class ColumnOperators(Operators):
         :paramref:`_sa.create_engine.empty_in_strategy` may be used to
         alter this behavior.
 
+        .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
+           ``notin_()`` in previous releases.  The previous name remains
+           available for backwards compatibility.
+
         .. versionchanged:: 1.2  The :meth:`.ColumnOperators.in_` and
-           :meth:`.ColumnOperators.notin_` operators
+           :meth:`.ColumnOperators.not_in` operators
            now produce a "static" expression for an empty IN sequence
            by default.
 
@@ -618,7 +622,10 @@ class ColumnOperators(Operators):
             :meth:`.ColumnOperators.in_`
 
         """
-        return self.operate(notin_op, other)
+        return self.operate(not_in_op, other)
+
+    # deprecated 1.4; see #5429
+    notin_ = not_in
 
     def notlike(self, other, escape=None):
         """implement the ``NOT LIKE`` operator.
@@ -654,12 +661,12 @@ class ColumnOperators(Operators):
         usage of ``IS`` may be desirable if comparing to boolean values
         on certain platforms.
 
-        .. seealso:: :meth:`.ColumnOperators.isnot`
+        .. seealso:: :meth:`.ColumnOperators.is_not`
 
         """
         return self.operate(is_, other)
 
-    def isnot(self, other):
+    def is_not(self, other):
         """Implement the ``IS NOT`` operator.
 
         Normally, ``IS NOT`` is generated automatically when comparing to a
@@ -667,10 +674,18 @@ class ColumnOperators(Operators):
         usage of ``IS NOT`` may be desirable if comparing to boolean values
         on certain platforms.
 
+        .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
+           ``isnot()`` in previous releases.  The previous name remains
+           available for backwards compatibility.
+
+
         .. seealso:: :meth:`.ColumnOperators.is_`
 
         """
-        return self.operate(isnot, other)
+        return self.operate(is_not, other)
+
+    # deprecated 1.4; see #5429
+    isnot = is_not
 
     def startswith(self, other, **kwargs):
         r"""Implement the ``startswith`` operator.
@@ -1269,8 +1284,12 @@ def is_(a, b):
 
 
 @comparison_op
-def isnot(a, b):
-    return a.isnot(b)
+def is_not(a, b):
+    return a.is_not(b)
+
+
+# 1.4 deprecated; see #5429
+isnot = is_not
 
 
 def collate(a, b):
@@ -1317,8 +1336,12 @@ def in_op(a, b):
 
 
 @comparison_op
-def notin_op(a, b):
-    return a.notin_(b)
+def not_in_op(a, b):
+    return a.not_in(b)
+
+
+# 1.4 deprecated; see #5429
+notin_op = not_in_op
 
 
 def distinct_op(a):
@@ -1529,9 +1552,9 @@ _PRECEDENCE = {
     like_op: 5,
     notlike_op: 5,
     in_op: 5,
-    notin_op: 5,
+    not_in_op: 5,
     is_: 5,
-    isnot: 5,
+    is_not: 5,
     eq: 5,
     ne: 5,
     is_distinct_from: 5,