Class Q

django/db/models/query_utils.py:41–247

Encapsulate filters as objects that can then be combined logically (using `&` and `|`).

class Q(tree.Node):
    """
    Encapsulate filters as objects that can then be combined logically (using
    `&` and `|`).
    """

    # Connection types
    AND = "AND"
    OR = "OR"
    XOR = "XOR"
    default = AND
    conditional = True
    connectors = (None, AND, OR, XOR)

    def __init__(self, *args, _connector=None, _negated=False, **kwargs):
        self._check_connector(_connector)
        super().__init__(
            children=[*args, *sorted(kwargs.items())],
            connector=_connector,
            negated=_negated,
        )

    @classmethod
    def create(cls, children=None, connector=None, negated=False):
        cls._check_connector(connector)
        return super().create(children=children, connector=connector, negated=negated)

    @classmethod
    def _check_connector(cls, connector):
        if connector not in cls.connectors:
            connector_reprs = ", ".join(f"{conn!r}" for conn in cls.connectors[1:])
            raise ValueError(f"connector must be one of {connector_reprs}, or None.")

    def _combine(self, other, conn):
        if getattr(other, "conditional", False) is False:
            raise TypeError(other)
        if not self:
            return other.copy()
        if not other and isinstance(other, Q):
            return self.copy()

        obj = self.create(connector=conn)
        obj.add(self, conn)
        obj.add(other, conn)
        return obj

    def __or__(self, other):
        return self._combine(other, self.OR)

    def __and__(self, other):
        return self._combine(other, self.AND)

    def __xor__(self, other):
        return self._combine(other, self.XOR)

    def __invert__(self):
        obj = self.copy()
        obj.negate()