Ticket #12725: Q.or_.diff

django/db/models/query_utils.py

@@ -168 +168 @@
         obj.negate()
         return obj
 
+    @classmethod
+    def or_(cls, *args, **kwargs):
+        """
+        OR together a bunch of Q objects and keyword arguments without cloning.
+        """
+        query = cls()
+        for q in args:
+            query.add(q, cls.OR)
+        for key, value in kwargs.items():
+            query.add(Q(**{key: value}), cls.OR)
+        return query
+
 class DeferredAttribute(object):
     """
     A wrapper for a deferred-loading field. When the value is read from this

docs/topics/db/queries.txt

@@ -692 +692 @@
 
 ... would not be valid.
 
+If you want to "OR" together a lot of arguments at once, it's more efficient to
+use ``Q.or_``.  ``Q.or_`` is a class method that takes any number of Q objects
+and keyword arguments and combines them with ``OR``, returning a new ``Q``
+object.  As mentioned above, all ``Q`` objects must come before any keyword
+arguments.
+
+The following queries are all equivalent::
+
+    Q(question__startswith='Who') | Q(pub_date__year=2005)
+
+    Q.or_(question__startswith='Who', pub_date__year=2005)
+
+    Q.or_(Q(question__startswith='Who'), pub_date__year=2005)
+
+    Q.or_(Q(question__startswith='Who'), Q(pub_date__year=2005))
+
 .. seealso::
 
     The `OR lookups examples`_ in the Django unit tests show some possible uses

tests/regressiontests/queries/models.py

@@ -418 +418 @@
 >>> Number.objects.filter(Q(num__gt=7) & Q(num__lt=12) | Q(num__lt=4))
 [<Number: 8>]
 
+The Q.or_ class method combines a bunch of Q objects and keyword arguments
+without all the cloning that occurs using |.
+>>> Number.objects.filter(Q.or_(Q(num__gt=7) & Q(num__lt=12), Q(num__lt=4)))
+[<Number: 8>]
+>>> Number.objects.filter(Q.or_(Q(num=4), Q(num=8), Q(num=12)))
+[<Number: 4>, <Number: 8>, <Number: 12>]
+>>> Number.objects.filter(Q.or_(Q(num=4), Q(num=8), num=12))
+[<Number: 4>, <Number: 8>, <Number: 12>]
+>>> Author.objects.filter(Q.or_(name='a3', item__name='one'))
+[<Author: a1>, <Author: a3>]
+>>> Author.objects.filter(Q.or_(Q(name='a3'), Q(item__name='one')))
+[<Author: a1>, <Author: a3>]
+>>> Author.objects.filter(Q.or_(Q(name='a3'), item__name='one'))
+[<Author: a1>, <Author: a3>]
+
 Bug #7872
 Another variation on the disjunctive filtering theme.