===============
Group Reference
===============

By default, a ``FilterSet`` validates and then filters its query parameters
independently of each other, ultimately resulting in a chain of ``.filter()``
calls. Due to the nature of filter chaining, it's not trivial to, for example,
make a group of filters that are mutually exclusive to each other.

Filter groups solve this limitation by processing subsets of parameters
together, enabling higher level validation and filtering behavior.

Validation
==========

A filter group only applies group-level validation. For example, a mutually
exclusive group is responsible for validating that *only* one of its parameters
is present. It is not responsible for validating the individual values, which
is still performed by the underlying filter instances.

Filtering
=========

In contrast to validation, a filter group overrides its filtering behavior.
Internally, a group may use the ``.filter()`` methods of its filters, but it
might also override it completely. For example, the ``RequiredGroup`` delegates
filtering to each of its underlying filters, while ``CombinedRequiredGroup``
constructs a ``Q`` object.

Builtin Groups:
===============

.. module:: django_filters.groups

.. autosummary::
    BaseFilterGroup
    ExclusiveGroup
    RequiredGroup
    CombinedGroup
    CombinedRequiredGroup

BaseFilterGroup
---------------
.. autoclass:: BaseFilterGroup

    .. automethod:: validate
    .. automethod:: filter
    .. automethod:: format_labels

ExclusiveGroup
--------------
.. autoclass:: ExclusiveGroup

RequiredGroup
-------------
.. autoclass:: RequiredGroup

CombinedGroup
-------------
.. autoclass:: CombinedGroup

CombinedRequiredGroup
---------------------
.. autoclass:: CombinedRequiredGroup