nautobot.apps.filters

Filterset base classes and mixins for app implementation.

nautobot.apps.filters.AutoDistinctFilterMixin

Mixin for MultipleChoiceFilter subclasses that derives the distinct flag from the filter's field path.

django_filters.MultipleChoiceFilter defaults to distinct=True, but a .distinct() call is only needed when a filter traverses a to-many relation, and it imposes a significant performance cost at scale otherwise. The model isn't known when a filter is instantiated as a class attribute, so resolution is deferred until self.model has been set (see django_filters.filterset.BaseFilterSet.__init__).

An explicitly provided distinct= argument always takes precedence, as does the class default in cases where the field path can't be resolved (a filter with a method, for example).

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

Bases: AutoDistinctFilterMixin, BooleanFilter

Subclass of the django-filters class by the same name, which auto-derives its distinct flag.

Note that an isnull=True lookup can never return duplicates, even across a to-many relation: it matches only objects that have no related rows, of which the outer join produces exactly one per object. The .distinct() is therefore skipped for that case regardless of the derived value.

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: AutoDistinctFilterMixin, 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.

distinct property writable

Derive distinct from the filter predicates, as this filter has no single field_name of its own.

Every predicate is OR'd into a single .filter() call, so a .distinct() is required if any one of them traverses a to-many relation. See AutoDistinctFilterMixin, of which this is a variation.

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

Bases: AutoDistinctFilterMixin, ModelMultipleChoiceFilter

Subclass of the django-filters class by the same name with an improved default label formulation.

Also auto-derives its distinct flag from the field path; see AutoDistinctFilterMixin.

label property writable

Override django_filters.Filter.label property to generate a more useful default label.

Examples:

>>> import django_filters
>>> from nautobot.core.filters import BaseFilterSet, ModelMultipleChoiceFilter
>>> class DemoFilterSet(BaseFilterSet):
...      class Meta:
...          model = Interface
...          fields = []
...      old_device = django_filters.ModelMultipleChoiceFilter(queryset=Device.objects.all(), field_name="device")
...      new_device = ModelMultipleChoiceFilter(queryset=Device.objects.all(), field_name="device")
...      device_name = ModelMultipleChoiceFilter(queryset=Device.objects.all(), field_name="device", to_field_name="name")
...
>>> DemoFilterSet().filters["old_device"].label
'Device'
>>> DemoFilterSet().filters["new_device"].label
'Device (ID)'
>>> DemoFilterSet().filters["device_name"].label
'Device (Name)'

nautobot.apps.filters.MultiValueBigNumberFilter

Bases: MultiValueNumberFilter

Subclass of MultiValueNumberFilter used for BigInteger model fields.

nautobot.apps.filters.MultipleChoiceFilter

Bases: AutoDistinctFilterMixin, MultipleChoiceFilter

Subclass of the django-filters class by the same name, which auto-derives its distinct flag.

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

to_field_name_label property

Override ModelMultipleChoiceFilter.to_field_name_label to indicate both field_name options.

Examples:

>>> VirtualMachineFilterSet().filters["software_image_files"].label
'Software Image Files (Image File Name or ID)'

__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