nautobot.apps.forms - Nautobot Documentation

Skip to content

# `nautobot.apps.forms`

Forms and fields for apps to use.

## `nautobot.apps.forms.APISelect`

Bases: `SelectWithDisabled`

A select widget populated via an API call

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`api_url` | `str` | API endpoint URL. Required if not set automatically by the parent field. | `None`
`api_version` | `str` | API version. | `None`

### `add_query_param(name, value)`

Add details for an additional query param in the form of a data-* JSON-encoded list attribute.

:param name: The name of the query param :param value: The value of the query param

## `nautobot.apps.forms.AddressFieldMixin`

Bases: `ModelForm`

ModelForm mixin for IPAddress based models.

## `nautobot.apps.forms.AutoPopulateWidget`

Bases: `SlugWidget`

Subclass SlugWidget and add support for auto-populate JavaScript logic from `form.js`.

## `nautobot.apps.forms.BootstrapMixin`

Bases: `BaseForm`

Add the base Bootstrap CSS classes to form elements.

Note that this only applies to form fields that are:

1. statically defined on the form class at declaration time, or
2. dynamically added to the form at init time by a class later in the MRO than this mixin.

If a class earlier in the MRO adds its own fields, it will have to ensure that the widgets are correctly configured.

## `nautobot.apps.forms.BulkEditForm`

Bases: `Form`

Base form for editing multiple objects in bulk.

Note that for models supporting custom fields and relationships, nautobot.extras.forms.NautobotBulkEditForm is a more powerful subclass and should be used instead of directly inheriting from this class.

### `post_save(obj)`

Post save action

## `nautobot.apps.forms.BulkEditNullBooleanSelect`

Bases: `NullBooleanSelect`

A Select widget for NullBooleanFields

## `nautobot.apps.forms.BulkRenameForm`

Bases: `Form`

An extendable form to be used for renaming objects in bulk.

## `nautobot.apps.forms.CSVChoiceField`

Bases: `ChoiceField`

Invert the provided set of choices to take the human-friendly label as input, and return the database value.

Despite the name, this is no longer used in CSV imports since 2.0, but is used in JSON/YAML import of DeviceTypes.

## `nautobot.apps.forms.CSVContentTypeField`

Bases: `CSVModelChoiceField`

Reference a ContentType in the form `{app_label}.{model}`.

Note: class name is misleading; this field is also used in numerous FilterSets where it has nothing to do with CSV.

### `prepare_value(value)`

Allow this field to support `{app_label}.{model}` style, null values, or PK-based lookups depending on how the field is used.

## `nautobot.apps.forms.CSVDataField`

Bases: `CharField`

A CharField (rendered as a Textarea) which expects CSV-formatted data.

Initial value is a list of headers corresponding to the required fields for the given serializer class.

This no longer actually does any CSV parsing or validation on its own, as that is now handled by the NautobotCSVParser class and the REST API serializers.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`required_field_names` | `list[str]` | List of field names representing required fields for this import. | `''`

## `nautobot.apps.forms.CSVFileField`

Bases: `FileField`

A FileField (rendered as a ClearableFileInput) which expects a file containing CSV-formatted data.

This no longer actually does any CSV parsing or validation on its own, as that is now handled by the NautobotCSVParser class and the REST API serializers.

### `to_python(data)`

For parity with CSVDataField, this returns the CSV text rather than an UploadedFile object.

## `nautobot.apps.forms.CSVModelChoiceField`

Bases: `ModelChoiceField`

Provides additional validation for model choices entered as CSV data.

Note: class name is misleading; the subclass CSVContentTypeField (below) is also used in FilterSets, where it has nothing to do with CSV data.

## `nautobot.apps.forms.CSVModelForm`

Bases: `ModelForm`

ModelForm used for the import of objects.

Note: the name is misleading as since 2.0 this is no longer used for CSV imports; however it is still used for JSON/YAML imports of DeviceTypes and their component templates.

## `nautobot.apps.forms.CSVMultipleChoiceField`

Bases: `CSVChoiceField`

A version of CSVChoiceField that supports and emits a list of choice values.

As with CSVChoiceField, the name is misleading, as this is no longer used for CSV imports, but is used for JSON/YAML import of DeviceTypes still.

### `to_python(value)`

Return a list of strings.

### `validate(value)`

Validate that each of the input values is in self.choices.

## `nautobot.apps.forms.CSVMultipleContentTypeField`

Bases: `MultipleContentTypeField`

Reference a list of `ContentType` objects in the form `{app_label}.{model}'.

Note: This is unused in Nautobot core at this time, but some apps (data-validation-engine) use this for non-CSV purposes, similar to CSVContentTypeField above.

### `prepare_value(value)`

Parse a comma-separated string of model names into a list of PKs.

## `nautobot.apps.forms.ColorSelect`

Bases: `Select`

Extends the built-in Select widget to colorize each .

## `nautobot.apps.forms.CommentField`

Bases: `CharField`

A textarea with support for Markdown rendering. Exists mostly just to add a standard help_text.

## `nautobot.apps.forms.ConfirmationForm`

Bases: `BootstrapMixin`, `ReturnURLForm`

A generic confirmation form. The form is not valid unless the confirm field is checked.

## `nautobot.apps.forms.ContactTeamModelFilterFormMixin`

Bases: `Form`

Adds the `contacts` and `teams` form fields to a filter form.

## `nautobot.apps.forms.ContentTypeSelect`

Bases: `StaticSelect2`

Appends an `api-value` attribute equal to the slugified model name for each ContentType. For example: console server port This attribute can be used to reference the relevant API endpoint for a particular ContentType.

## `nautobot.apps.forms.CustomFieldModelCSVForm`

Bases: `CSVModelForm`, `CustomFieldModelFormMixin`

Base class for CSV/JSON/YAML import of models that support custom fields.

TODO: The class name is a misnomer; as of 2.0 this class is not used for any CSV imports, as that's now handled by the REST API. However it is still used when importing component-templates as part of a JSON/YAML DeviceType import.

## `nautobot.apps.forms.CustomFieldModelFormMixin`

Bases: `ModelForm`

## `nautobot.apps.forms.DatePicker`

Bases: `TextInput`

Date picker using Flatpickr.

## `nautobot.apps.forms.DateTimePicker`

Bases: `TextInput`

DateTime picker using Flatpickr.

## `nautobot.apps.forms.DynamicFilterForm`

Bases: `BootstrapMixin`, `Form`

Form for dynamically inputting filter values for an object list.

## `nautobot.apps.forms.DynamicGroupModelFormMixin`

Bases: `ModelForm`

Mixin to add `dynamic_groups` field to model create/edit forms where applicable.

## `nautobot.apps.forms.DynamicModelChoiceField`

Bases: `DynamicModelChoiceMixin`, `ModelChoiceField`

Override get_bound_field() to avoid pre-populating field choices with a SQL query. The field will be rendered only with choices set via bound data. Choices are populated on-demand via the APISelect widget.

### `clean(value)`

When null option is enabled and "None" is sent as part of a form to be submitted, it is sent as the string 'null'. This will check for that condition and gracefully handle the conversion to a NoneType.

## `nautobot.apps.forms.DynamicModelChoiceMixin`

:param display_field: The name of the attribute of an API response object to display in the selection list :param query_params: A dictionary of additional key/value pairs to attach to the API request :param initial_params: A dictionary of child field references to use for selecting a parent field's initial value :param null_option: The string used to represent a null selection (if any) :param disabled_indicator: The name of the field which, if populated, will disable selection of the choice (optional) :param depth: Nested serialization depth when making API requests (default: `0` or a flat representation)

### `prepare_value(value)`

Augment the behavior of forms.ModelChoiceField.prepare_value().

Specifically, if `value` is a PK, but we have `to_field_name` set, we need to look up the model instance from the given PK, so that the base class will get the appropriate field value rather than just keeping the PK, because the rendered form field needs this in order to correctly prepopulate a default selection.

## `nautobot.apps.forms.DynamicModelMultipleChoiceField`

Bases: `DynamicModelChoiceMixin`, `ModelMultipleChoiceField`

A multiple-choice version of DynamicModelChoiceField.

## `nautobot.apps.forms.ExpandableIPAddressField`

Bases: `CharField`

A field which allows for expansion of IP address ranges Example: '192.0.2.[1-254]/24' => ['192.0.2.1/24', '192.0.2.2/24', '192.0.2.3/24' ... '192.0.2.254/24']

## `nautobot.apps.forms.ExpandableNameField`

Bases: `CharField`

A field which allows for numeric range expansion Example: 'Gi0/[1-3]' => ['Gi0/1', 'Gi0/2', 'Gi0/3']

## `nautobot.apps.forms.ImportForm`

Bases: `BootstrapMixin`, `Form`

Generic form for creating an object from JSON/YAML data

## `nautobot.apps.forms.JSONArrayFormField`

Bases: `JSONField`

A FormField counterpart to JSONArrayField. Replicates ArrayFormField's base field validation: Field values are validated as JSON Arrays, and each Array element is validated by `base_field` validators.

### `clean(value)`

Validate `value` and return its "cleaned" value as an appropriate Python object. Raise ValidationError for any errors.

### `has_changed(initial, data)`

Return True if `data` differs from `initial`.

### `prepare_value(value)`

Return a string of this value.

### `run_validators(value)`

Runs all validators against `value` and raise ValidationError if necessary. Some validators can't be created at field initialization time.

### `to_python(value)`

Convert `value` into JSON, raising django.core.exceptions.ValidationError if the data can't be converted. Return the converted value.

### `valid_value(value)`

Check to see if the provided value is a valid choice.

### `validate(value)`

Validate `value` and raise ValidationError if necessary.

## `nautobot.apps.forms.JSONField`

Bases: `JSONField`

Custom wrapper around Django's built-in JSONField to avoid presenting "null" as the default text.

## `nautobot.apps.forms.LaxURLField`

Bases: `URLField`

Modifies Django's built-in URLField to remove the requirement for fully-qualified domain names (e.g. http://myserver/ is valid)

## `nautobot.apps.forms.MultiMatchModelMultipleChoiceField`

Bases: `DynamicModelChoiceMixin`, `ModelMultipleChoiceField`

Filter field to support matching on the PK or `to_field_name` fields (defaulting to `slug` if not specified).

Raises ValidationError if none of the fields match the requested value.

## `nautobot.apps.forms.MultiValueCharField`

Bases: `CharField`

CharField that takes multiple user character inputs and render them as tags in the form field. Press enter to complete an input.

## `nautobot.apps.forms.MultiValueCharInput`

Bases: `StaticSelect2Multiple`

Manual text input with tagging enabled. Press enter to create a new entry.

## `nautobot.apps.forms.MultipleContentTypeField`

Bases: `ModelMultipleChoiceField`

Field for choosing any number of `ContentType` objects.

Optionally can restrict the available ContentTypes to those supporting a particular feature only. Optionally can pass the selection through as a list of `{app_label}.{model}` strings instead of PK values.

### `__init__(*args, feature=None, choices_as_strings=False, **kwargs)`

Construct a MultipleContentTypeField.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`feature` | `str` | Feature name to use in constructing a FeatureQuery to restrict the available ContentTypes. | `None`
`choices_as_strings` | `bool` | If True, render selection as a list of `"{app_label}.{model}"` strings. | `False`

## `nautobot.apps.forms.NautobotBulkEditForm`

Bases: `BootstrapMixin`, `CustomFieldModelBulkEditFormMixin`, `NoteModelBulkEditFormMixin`, `RelationshipModelBulkEditFormMixin`

Base class for bulk-edit forms for models that support relationships, custom fields and notes.

## `nautobot.apps.forms.NautobotFilterForm`

Bases: `BootstrapMixin`, `ContactTeamModelFilterFormMixin`, `CustomFieldModelFilterFormMixin`, `RelationshipModelFilterFormMixin`

This class exists to combine common functionality and is used to inherit from throughout the codebase where all of ContactTeamModelFilterFormMixin, CustomFieldModelFilterFormMixin, and RelationshipModelFilterFormMixin are needed.

## `nautobot.apps.forms.NautobotModelForm`

Bases: `BootstrapMixin`, `CustomFieldModelFormMixin`, `DynamicGroupModelFormMixin`, `NoteModelFormMixin`, `RelationshipModelFormMixin`

This class exists to combine common functionality and is used to inherit from throughout the codebase where all of BootstrapMixin, CustomFieldModelFormMixin, RelationshipModelFormMixin, and NoteModelFormMixin are needed.

## `nautobot.apps.forms.NoteFormBase`

Bases: `Form`

Base for the NoteModelFormMixin and NoteModelBulkEditFormMixin.

## `nautobot.apps.forms.NoteModelBulkEditFormMixin`

Bases: `BulkEditForm`, `NoteFormBase`

Bulk-edit form mixin for models that support Notes.

## `nautobot.apps.forms.NumericArrayField`

Bases: `SimpleArrayField`

Basic array field that takes comma-separated or hyphenated ranges.

## `nautobot.apps.forms.PrefixFieldMixin`

Bases: `ModelForm`

ModelForm mixin for IPNetwork based models.

## `nautobot.apps.forms.RelationshipModelBulkEditFormMixin`

Bases: `BulkEditForm`

Bulk-edit form mixin for models that support Relationships.

### `save_relationships(*, instance, nullified_fields)`

Helper method to be called from BulkEditView.post().

## `nautobot.apps.forms.RelationshipModelFilterFormMixin`

Bases: `Form`

## `nautobot.apps.forms.RelationshipModelFormMixin`

Bases: `ModelForm`

### `clean()`

First check for any required relationships errors and if there are any, add them via form field errors. Then verify that any requested RelationshipAssociations do not violate relationship cardinality restrictions.

- For TYPE_ONE_TO_MANY and TYPE_ONE_TO_ONE relations, if the form's object is on the "source" side of the relationship, verify that the requested "destination" object(s) do not already have any existing RelationshipAssociation to a different source object.
- For TYPE_ONE_TO_ONE relations, if the form's object is on the "destination" side of the relationship, verify that the requested "source" object does not have an existing RelationshipAssociation to a different destination object.

## `nautobot.apps.forms.ReturnURLForm`

Bases: `Form`

Provides a hidden return URL field to control where the user is directed after the form is submitted.

## `nautobot.apps.forms.RoleModelBulkEditFormMixin`

Bases: `Form`

Mixin to add non-required `role` choice field to forms.

## `nautobot.apps.forms.RoleModelFilterFormMixin`

Bases: `Form`

Mixin to add non-required `role` multiple-choice field to filter forms.

## `nautobot.apps.forms.SelectWithDisabled`

Bases: `Select`

Modified the stock Select widget to accept choices using a dict() for a label. The dict for each option must include 'label' (string) and 'disabled' (boolean).

## `nautobot.apps.forms.SelectWithPK`

Bases: `StaticSelect2`

Include the primary key of each option in the option label (e.g. "Router7 (4721)").

## `nautobot.apps.forms.SlugField`

Bases: `SlugField`

Extend the built-in SlugField to automatically populate from a field called `name` unless otherwise specified.

### `__init__(slug_source='name', *args, **kwargs)`

Instantiate a SlugField.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`slug_source` | `(str, tuple)` | Name of the field (or a list of field names) that will be used to suggest a slug. | `'name'`

## `nautobot.apps.forms.SlugWidget`

Bases: `TextInput`

Subclass TextInput and add a slug regeneration button next to the form field.

## `nautobot.apps.forms.SmallTextarea`

Bases: `Textarea`

Subclass used for rendering a smaller textarea element.

## `nautobot.apps.forms.StaticSelect2`

Bases: `SelectWithDisabled`

A static

## `nautobot.apps.forms.StatusModelBulkEditFormMixin`

Bases: `Form`

Mixin to add non-required `status` choice field to forms.

## `nautobot.apps.forms.StatusModelFilterFormMixin`

Bases: `Form`

Mixin to add non-required `status` multiple-choice field to filter forms.

## `nautobot.apps.forms.TableConfigForm`

Bases: `BootstrapMixin`, `Form`

Form for configuring user's table preferences.

## `nautobot.apps.forms.TagFilterField`

Bases: `DynamicModelMultipleChoiceField`

A filter field for the tags of a model. Only the tags used by a model are displayed.

:param model: The model of the filter

## `nautobot.apps.forms.TimePicker`

Bases: `TextInput`

Time picker using Flatpickr.

## `nautobot.apps.forms.add_blank_choice(choices)`

Add a blank choice to the beginning of a choices list.

## `nautobot.apps.forms.add_field_to_filter_form_class(form_class, field_name, field_obj)`

Attach a field to an existing filter form class.

## `nautobot.apps.forms.expand_alphanumeric_pattern(string)`

Expand an alphabetic pattern into a list of strings.

## `nautobot.apps.forms.expand_ipaddress_pattern(string, ip_version)`

Expand an IP address pattern into a list of strings. Examples: '192.0.2.[1,2,100-250]/24' => ['192.0.2.1/24', '192.0.2.2/24', '192.0.2.100/24' ... '192.0.2.250/24'] '2001:db8:0:[0,fd-ff]::/64' => ['2001:db8:0:0::/64', '2001:db8:0:fd::/64', ... '2001:db8:0:ff::/64']

## `nautobot.apps.forms.form_from_model(model, fields)`

Return a Form class with the specified fields derived from a model. This is useful when we need a form to be used for creating objects, but want to avoid the model's validation (e.g. for bulk create/edit functions). All fields are marked as not required.

## `nautobot.apps.forms.parse_alphanumeric_range(string)`

Expand an alphanumeric range (continuous or not) into a list. 'a-d,f' => [a, b, c, d, f] '0-3,a-d' => [0, 1, 2, 3, a, b, c, d]

## `nautobot.apps.forms.parse_numeric_range(input_string, base=10)`

Expand a numeric range (continuous or not) into a sorted decimal or hexadecimal list, as specified by the base parameter '0-3,5' => [0, 1, 2, 3, 5] '2,8-b,d,f' => [2, 8, 9, a, b, d, f]

## `nautobot.apps.forms.restrict_form_fields(form, user, action='view')`

Restrict all form fields which reference a RestrictedQuerySet. This ensures that users see only permitted objects as available choices.