Skip to content

# `nautobot.apps.filters`

Filterset base classes and mixins for app implementation.

## `nautobot.apps.filters.BaseFilterSet`

Bases: `FilterSet`

A base filterset which provides common functionality to all Nautobot filtersets.

### `errors` `property`

Extend FilterSet.errors to potentially include additional errors from settings.STRICT_FILTERING.

### `add_filter(new_filter_name, new_filter_field)` `classmethod`

Allow filters to be added post-generation on import.

Will provide `<field_name>__<lookup_expr>` generation automagically.

### `filter_for_lookup(field, lookup_type)` `classmethod`

Override filter_for_lookup method to set ChoiceField Filter to MultipleChoiceFilter.

Note: Any CharField or IntegerField with choices set is a ChoiceField.

### `get_filters()` `classmethod`

Override filter generation to support dynamic lookup expressions for certain filter types.

### `is_valid()`

Extend FilterSet.is_valid() to potentially enforce settings.STRICT_FILTERING.

## `nautobot.apps.filters.ConfigContextRoleFilter`

Bases: `NaturalKeyOrPKMultipleChoiceFilter`

Limit role choices to the available role choices for Device and VM

## `nautobot.apps.filters.ContentTypeChoiceFilter`

Bases: `ContentTypeFilterMixin`, `ChoiceFilter`

Allows character-based ContentType filtering by . (e.g. "dcim.location") but an explicit set of choices must be provided.

Example use on a `FilterSet`:

    content_type = ContentTypeChoiceFilter(
        choices=FeatureQuery("dynamic_groups").get_choices,
    )

In most cases you should use `ContentTypeMultipleChoiceFilter` instead.

## `nautobot.apps.filters.ContentTypeFilter`

Bases: `ContentTypeFilterMixin`, `CharFilter`

Allows character-based ContentType filtering by . (e.g. "dcim.location").

Does not support limiting of choices. Can be used without arguments on a `FilterSet`:

    content_type = ContentTypeFilter()

## `nautobot.apps.filters.ContentTypeFilterMixin`

Mixin to allow specifying a ContentType by . (e.g. "dcim.location").

## `nautobot.apps.filters.ContentTypeMultipleChoiceFilter`

Bases: `MultipleChoiceFilter`

Allows multiple-choice ContentType filtering by . (e.g. "dcim.location").

Does NOT allow filtering by PK at this time; it would need to be reimplemented similar to NaturalKeyOrPKMultipleChoiceFilter as a breaking change.

Defaults to joining multiple options with "AND". Pass `conjoined=False` to override this behavior to join with "OR" instead.

Example use on a `FilterSet`:

    content_types = ContentTypeMultipleChoiceFilter(
        choices=FeatureQuery("statuses").get_choices,
    )

## `nautobot.apps.filters.CustomFieldModelFilterSetMixin`

Bases: `FilterSet`

Dynamically add a Filter for each CustomField applicable to the parent model. Add filters for extra lookup expressions on supported CustomField types.

## `nautobot.apps.filters.FilterExtension`

Class that may be returned by a registered Filter Extension function.

## `nautobot.apps.filters.MappedPredicatesFilterMixin`

A filter mixin to provide the ability to specify fields and lookup expressions to use for filtering.

A mapping of filter predicates (field_name: lookup_expr) must be provided to the filter when declared on a filterset. This mapping is used to construct a `Q` query to filter based on the provided predicates.

By default a predicate for `{"id": "iexact"}` (`id__exact`) will always be included.

Example:

    q = SearchFilter(
        filter_predicates={
            "comments": "icontains",
            "name": "icontains",
        },
    )

Optionally you may also provide a callable to use as a preprocessor for the filter predicate by providing the value as a nested dict with "lookup_expr" and "preprocessor" keys. For example:

    q = SearchFilter(
        filter_predicates={
            "asn": {
                "lookup_expr": "exact",
                "preprocessor": int,
            },
        },
    )

This tells the filter to try to cast `asn` to an `int`. If it fails, this predicate will be skipped.

### `generate_query(value, **kwargs)`

Given a `value`, return a `Q` object for 2-tuple of `predicate=value`. Filter predicates are read from the instance filter. Any `kwargs` are ignored.

## `nautobot.apps.filters.MultiValueBigNumberFilter`

Bases: `MultiValueNumberFilter`

Subclass of MultiValueNumberFilter used for BigInteger model fields.

## `nautobot.apps.filters.NameSearchFilterSet`

Bases: `FilterSet`

A base class for adding the search method to models which only expose the `name` field in searches.

## `nautobot.apps.filters.NaturalKeyOrPKMultipleChoiceFilter`

Bases: `ModelMultipleChoiceFilter`

Filter that supports filtering on values matching the `pk` field and another field of a foreign-key related object. The desired field is set using the `to_field_name` keyword argument on filter initialization (defaults to `name`).

NOTE that the `to_field_name` field does not have to be a "true" natural key (ie. unique), it was just the best name we could come up with for this filter

### `__init__(*args, prefers_id=False, **kwargs)`

Initialize the NaturalKeyOrPKMultipleChoiceFilter.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`prefers_id` | `bool` | Prefer PK (ID) over the 'to_field_name'. Defaults to False. | `False`

### `get_filter_predicate(v)`

Override base filter behavior to force the filter to use the `pk` field instead of the natural key in the generated filter.

## `nautobot.apps.filters.NautobotFilterSet`

Bases: `BaseFilterSet`, `CreatedUpdatedModelFilterSetMixin`, `RelationshipModelFilterSetMixin`, `CustomFieldModelFilterSetMixin`

This class exists to combine common functionality and is used as a base class throughout the codebase where all of BaseFilterSet, CreatedUpdatedModelFilterSetMixin, RelationshipModelFilterSetMixin and CustomFieldModelFilterSetMixin are needed.

## `nautobot.apps.filters.NumericArrayFilter`

Bases: `NumberFilter`

Filter based on the presence of an integer within an ArrayField.

## `nautobot.apps.filters.PrefixFilter`

Bases: `NaturalKeyOrPKMultipleChoiceFilter`

Filter that supports filtering a foreign key to Prefix by either its PK or by a literal `prefix` string.

## `nautobot.apps.filters.RelatedMembershipBooleanFilter`

Bases: `BooleanFilter`

BooleanFilter for related objects that will explicitly perform `isnull` lookups. The `field_name` argument is required and must be set to the related field on the model.

This should be used instead of a default `BooleanFilter` paired `method=` argument to test for the existence of related objects.

Example:

    has_modules = RelatedMembershipBooleanFilter(
        field_name="module_bays__installed_module",
        label="Has modules",
    )

    This would generate a filter that returns instances that have at least one module
    bay with an installed module. The `has_modules=False` filter would exclude instances
    with at least one module bay with an installed module.

    Set `exclude=True` to reverse the behavior of the filter. This __may__ be useful
    for filtering on null directly related fields but this filter is not smart enough
    to differentiate between `fieldA__fieldB__isnull` and `fieldA__isnull` so it's not
    suitable for cases like the `has_empty_module_bays` filter where an instance may
    not have any module bays.

    See the below table for more information:

    | value       | exclude          | Result
    |-------------|------------------|-------
    | True        | False (default)  | Return instances with at least one non-null match -- qs.filter(field_name__isnull=False)
    | False       | False (default)  | Exclude instances with at least one non-null match -- qs.exclude(field_name__isnull=False)
    | True        | True             | Return instances with at least one null match -- qs.filter(field_name__isnull=True)
    | False       | True             | Exclude instances with at least one null match -- qs.exclude(field_name__isnull=True)

## `nautobot.apps.filters.RelationshipFilter`

Bases: `ModelMultipleChoiceFilter`

Filter objects by the presence of associations on a given Relationship.

## `nautobot.apps.filters.RelationshipModelFilterSetMixin`

Bases: `FilterSet`

Filterset for relationships applicable to the parent model.

## `nautobot.apps.filters.RoleFilter`

Bases: `NaturalKeyOrPKMultipleChoiceFilter`

Filter field used for filtering Role fields.

## `nautobot.apps.filters.RoleModelFilterSetMixin`

Bases: `FilterSet`

Mixin to add a `role` filter field to a FilterSet.

## `nautobot.apps.filters.SearchFilter`

Bases: `MappedPredicatesFilterMixin`, `CharFilter`

Provide a search filter for use on filtersets as the `q=` parameter.

See the docstring for `nautobot.core.filters.MappedPredicatesFilterMixin` for usage.

## `nautobot.apps.filters.StatusFilter`

Bases: `NaturalKeyOrPKMultipleChoiceFilter`

Filter field used for filtering Status fields.

## `nautobot.apps.filters.StatusModelFilterSetMixin`

Bases: `FilterSet`

Mixin to add a `status` filter field to a FilterSet.

## `nautobot.apps.filters.TagFilter`

Bases: `NaturalKeyOrPKMultipleChoiceFilter`

Match on one or more assigned tags. If multiple tags are specified (e.g. ?tag=foo&tag=bar), the queryset is filtered to objects matching all tags.

## `nautobot.apps.filters.TenancyModelFilterSetMixin`

Bases: `FilterSet`

An inheritable FilterSet for models which support Tenant assignment.

## `nautobot.apps.filters.TreeNodeMultipleChoiceFilter`

Bases: `NaturalKeyOrPKMultipleChoiceFilter`

Filter that matches on the given model(s) (identified by name and/or pk) as well as their tree descendants.

For example, if we have:

    Location "Earth"
      Location "USA"
        Location "GA" <- Location "Athens"
        Location "NC" <- Location "Durham"

a NaturalKeyOrPKMultipleChoiceFilter on Location for {"parent": "USA"} would only return "GA" and "NC" since that is the only two locations that have an immediate parent "USA" but a TreeNodeMultipleChoiceFilter on Location for {"parent": "USA"} would match both "Athens" and "Durham" in addition to "GA" and "NC".

### `generate_query(value, qs=None, **kwargs)`

Given a filter value, return a `Q` object that accounts for nested tree node descendants.

## `nautobot.apps.filters.multivalue_field_factory(field_class, widget=django_forms.SelectMultiple)`

Given a form field class, return a subclass capable of accepting multiple values. This allows us to OR on multiple filter values while maintaining the field's built-in validation. Example: GET /api/dcim/devices/?name=foo&name=bar