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,
)

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").

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,
)

filter(qs, value)

Filter on value, which should be list of content-type names.

e.g. ['dcim.device', 'dcim.rack']

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).

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.RelatedMembershipBooleanFilter

Bases: BooleanFilter

BooleanFilter for related objects that will explicitly perform exclude=True and 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_interfaces = RelatedMembershipBooleanFilter(
    field_name="interfaces",
    label="Has interfaces",
)

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.

__init__(*args, **kwargs)

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