Finishing touches to where implementation - thanks to dcrosta

Refs #242

AUTHORS

@@ -5,3 +5,4 @@ Florian Schlachter <flori@n-schlachter.de>
 Steve Challis <steve@stevechallis.com>
 Ross Lawley <ross.lawley@gmail.com>
 Wilson Júnior <wilsonpjunior@gmail.com>
+Dan Crosta https://github.com/dcrosta

docs/changelog.rst

@@ -5,6 +5,7 @@ Changelog
 Changes in dev
 ==============
 
+- Added where() - filter to allowing users to specify query expressions as Javascript
 - Added SequenceField - for creating sequential counters
 - Added update() convenience method to a document
 - Added cascading saves - so changes to Referenced documents are saved on .save()

mongoengine/fields.py

@@ -620,7 +620,7 @@ class GenericReferenceField(BaseField):
     """A reference to *any* :class:`~mongoengine.document.Document` subclass
     that will be automatically dereferenced on access (lazily).
 
-    note:  Any documents used as a generic reference must be registered in the
+    ..note ::  Any documents used as a generic reference must be registered in the
     document registry.  Importing the model will automatically register it.
 
     .. versionadded:: 0.3

mongoengine/queryset.py

@@ -1401,6 +1401,10 @@ class QuerySet(object):
         """Filter ``QuerySet`` results with a ``$where`` clause (a Javascript
         expression). Performs automatic field name substitution like
         :meth:`mongoengine.queryset.Queryset.exec_js`.
+
+        .. note:: When using this mode of query, the database will call your
+                  function, or evaluate your predicate clause, for each object
+                  in the collection.
         """
         where_clause = self._sub_js_fields(where_clause)
         self._where_clause = where_clause

tests/queryset.py

@@ -2531,6 +2531,19 @@ class QuerySetTest(unittest.TestCase):
         self.assertEqual(1, len(results))
         self.assertTrue(a in results)
 
+        query = IntPair.objects.where('function() { return this[~fielda] >= this[~fieldb] }')
+        self.assertEqual('function() { return this["fielda"] >= this["fieldb"] }', query._where_clause)
+        results = list(query)
+        self.assertEqual(2, len(results))
+        self.assertTrue(a in results)
+        self.assertTrue(c in results)
+
+        def invalid_where():
+            list(IntPair.objects.where(fielda__gte=3))
+
+        self.assertRaises(TypeError, invalid_where)
+
+
 class QTest(unittest.TestCase):
 
     def setUp(self):