PYTHON-2130 Note that $where does not support Code with scope in MongoDB 4.4+

Author: ShaneHarvey

pymongo/cursor.py

@@ -915,24 +915,34 @@ def comment(self, comment):
         return self
 
     def where(self, code):
-        """Adds a $where clause to this query.
+        """Adds a `$where`_ clause to this query.
 
         The `code` argument must be an instance of :class:`basestring`
         (:class:`str` in python 3) or :class:`~bson.code.Code`
         containing a JavaScript expression. This expression will be
         evaluated for each document scanned. Only those documents
         for which the expression evaluates to *true* will be returned
         as results. The keyword *this* refers to the object currently
-        being scanned.
+        being scanned. For example::
+
+            # Find all documents where field "a" is less than "b" plus "c".
+            for doc in db.test.find().where('this.a < (this.b + this.c)'):
+                print(doc)
 
         Raises :class:`TypeError` if `code` is not an instance of
         :class:`basestring` (:class:`str` in python 3). Raises
         :class:`~pymongo.errors.InvalidOperation` if this
         :class:`Cursor` has already been used. Only the last call to
         :meth:`where` applied to a :class:`Cursor` has any effect.
 
+        .. note:: MongoDB 4.4 drops support for :class:`~bson.code.Code`
+          with scope variables. Consider using `$expr`_ instead.
+
         :Parameters:
           - `code`: JavaScript expression to use as a filter
+
+        .. _$expr: https://docs.mongodb.com/manual/reference/operator/query/expr/
+        .. _$where: https://docs.mongodb.com/manual/reference/operator/query/where/
         """
         self.__check_okay_to_chain()
         if not isinstance(code, Code):

test/test_cursor.py

@@ -829,7 +829,6 @@ def test_count_with_hint(self):
             self.assertEqual(2, collection.find().hint("x_1").count())
             self.assertEqual(2, collection.find().hint([("x", 1)]).count())
 
-    @client_context.require_version_max(4, 3, 2)  # PYTHON-2130
     @ignore_deprecations
     def test_where(self):
         db = self.db
@@ -845,8 +844,20 @@ def test_where(self):
         self.assertEqual(3, len(list(db.test.find().where('this.x < 3'))))
         self.assertEqual(3,
                          len(list(db.test.find().where(Code('this.x < 3')))))
-        self.assertEqual(3, len(list(db.test.find().where(Code('this.x < i',
-                                                               {"i": 3})))))
+
+        code_with_scope = Code('this.x < i', {"i": 3})
+        if client_context.version.at_least(4, 3, 3):
+            # MongoDB 4.4 removed support for Code with scope.
+            with self.assertRaises(OperationFailure):
+                list(db.test.find().where(code_with_scope))
+
+            code_with_empty_scope = Code('this.x < 3', {})
+            with self.assertRaises(OperationFailure):
+                list(db.test.find().where(code_with_empty_scope))
+        else:
+            self.assertEqual(
+                3, len(list(db.test.find().where(code_with_scope))))
+
         self.assertEqual(10, len(list(db.test.find())))
 
         self.assertEqual(3, db.test.find().where('this.x < 3').count())