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

1 files changed, 35 insertions, 12 deletions

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,