nautobot.apps.tables

Utilities for apps to implement data tables.

nautobot.apps.tables.BaseTable

Bases: Table

Default table for object lists.

RowOverviewsVisibility

Bases: Enum

Whether a table renders the per-row button that expands the row to reveal the object's overview.

Attributes:

Name	Type	Description
HIDE	str	Never render the button (value: "hide").
SHOW	str	Always render the button (value: "show").
TABLE_DEFAULT	str	Leave the decision to the table's Meta.show_row_overviews (value: "table_default").

__init__(*args, table_changes_pending=False, saved_view=None, user=None, hide_hierarchy_ui=False, order_by=None, orderable=None, row_attrs=None, data_transform_callback=None, configurable=False, is_object_embedded_search_results=False, row_overviews_visibility=RowOverviewsVisibility.HIDE, **kwargs)

Instantiate a BaseTable.

Parameters:

Name	Type	Description	Default
*args	list	Passed through to django_tables2.Table	()
table_changes_pending	bool	TODO	False
saved_view	SavedView	TODO	None
user	User	Personalize table display for the given user (optional)	None
hide_hierarchy_ui	bool	Whether to display or hide hierarchy indentation of nested objects.	False
order_by	list	Field(s) to sort by	None
orderable	bool	Enable/disable column ordering on this table.	None
row_attrs	dict	Add custom html attributes to the table rows. Allows custom HTML attributes to be specified which will be added to the <tr> tag of the rendered table.	None
data_transform_callback	function	A function that takes the given data as an input and returns new data. Runs after all of the queryset auto-optimization performed by this class. Used for example in IPAM views to inject "fake" records for "available" Prefixes, IPAddresses, or VLANs.	None
configurable	bool	Include cog wheel icon with "Table Configuration" form; this arg is ignored when is_object_embedded_search_results is set to True.	False
is_object_embedded_search_results	bool	When set to True disable table configuration and sorting, render columns unaffected by any user configuration, with static order and visibility.	False
row_overviews_visibility	RowOverviewsVisibility	Whether to include a per-row button that expands the row to reveal the object's overview. Defaults to HIDE, opting out regardless of Meta. Pass TABLE_DEFAULT to defer to the table's Meta.show_row_overviews, which tables that expand their rows to children instead set to False.	HIDE
**kwargs	dict	Passed through to django_tables2.Table	{}

Warning: Do not modify/set the base_columns attribute after BaseTable class is instantiated. Do not modify/set the base_columns attribute after calling super().init() of BaseTable class.

add_conditional_prefetch(table_field, db_column=None, prefetch=None)

Conditionally prefetch the specified database column if the related table field is visible.

Parameters:

Name	Type	Description	Default
table_field	str	Name of the field on the table to check for visibility. Also used as the prefetch field if neither db_column nor prefetch is specified.	required
db_column	str	Optionally specify the db column to prefetch. Mutually exclusive with prefetch.	None
prefetch	Prefetch	Optionally specify a prefetch object. Mutually exclusive with db_column.	None

serializer_paths_by_visible_column(serializer_class)

Map each of this table's visible data columns to its serializer field path, or to None if it has none.

The mapping is heuristic: a column maps to accessor.replace(".", "__") if the head of that path is a field of the given serializer, and a custom-field column maps to its own cf_<key> name; a table may override individual columns via column_serializer_field_overrides. Columns with no serializer counterpart (buttons, computed fields, relationships, ...) map to None, so that a caller can report what it could not carry over; the non-data pk and actions columns are left out of the mapping entirely.

A LinkedCountColumn never maps to its own name, even where the serializer declares a matching field, since such a field reads an annotation this table adds for display rather than anything stored on the record. It maps instead to the relation it counts, where the serializer exposes that relation and LinkedCountColumn.counted_relation() can identify it -- so vrf_count carries the VRFs themselves rather than dropping out. Otherwise it maps to None.

Returns:

Type	Description
dict	{column_name: serializer_field_path_or_None}, in column display order.

serializer_paths_for_visible_columns(serializer_class)

The serializer field paths of this table's visible columns, for use as a default export field selection.

Columns with no serializer counterpart are omitted; see serializer_paths_by_visible_column(), which additionally reports those. Duplicates are collapsed, two columns being able to map to the same path, since a field selection names each field once.

nautobot.apps.tables.BooleanColumn

Bases: Column

Custom implementation of BooleanColumn to render a nicely-formatted checkmark or X icon instead of a Unicode character.

nautobot.apps.tables.ButtonsColumn

Bases: TemplateColumn

Render detail, changelog, edit, and delete buttons for an object.

Parameters:

Name	Type	Description	Default
model	type(Model)	Model class to use for calculating URL view names	required
prepend_template	Optional[str]	Additional template content to render in the column	''
return_url_extra	Optional[str]	String to append to the return URL (e.g. for specifying a tab)	''

nautobot.apps.tables.ChoiceFieldColumn

Bases: Column

Render a ChoiceField value inside a indicating a particular CSS class. This is useful for displaying colored choices. The CSS class is derived by calling .get_FOO_class() on the row record.

nautobot.apps.tables.ColorColumn

Bases: Column

Display a color (#RRGGBB).

nautobot.apps.tables.ColoredLabelColumn

Bases: TemplateColumn

Render a colored label (e.g. for DeviceRoles).

nautobot.apps.tables.ComputedFieldColumn

Bases: Column

Display computed fields in the appropriate format.

nautobot.apps.tables.ContentTypesColumn

Bases: ManyToManyColumn

Display a list of content_types m2m assigned to an object.

Default sorting of content-types is by pk. This sorting comes at a per-row performance hit to querysets for table views. If this becomes an issue, set sort_items=False.

Parameters:

Name	Type	Description	Default
sort_items	bool	Whether to sort by (app_label, name).	True
truncate_words	Optional[int]	Number of words at which to truncate, or None to disable.	None

filter(qs)

Overload filter to optionally sort items.

render(value)

Overload render to optionally truncate words.

nautobot.apps.tables.CustomFieldColumn

Bases: Column

Display custom fields in the appropriate format.

nautobot.apps.tables.LinkedCountColumn

Bases: Column

Render a count of related objects linked to a filtered URL, or if a single related object is present, the object.

Parameters:

Name	Type	Description	Default
viewname	str	The list view name to use for URL resolution, for example "dcim:location_list"	required
url_params	dict	Query parameters to apply to filter the list URL (e.g. {"vlans": "pk"} will add ?vlans=<record.pk> to the linked list URL)	None
view_kwargs	dict	Additional kwargs to pass to reverse() for list URL resolution. Rarely used.	None
lookup	str	The field name on the base record that can be used to query the related objects. If not specified, nautobot.core.utils.lookup.get_related_field_for_models() will be called at render time to attempt to intelligently find the appropriate field. Nested lookups via __ are supported (e.g. "interfaces__device"): the first segment is prefetched and the remaining segments are followed on the related object via select_related.	None
reverse_lookup	str	The reverse lookup parameter to use to derive the count. If not specified, the first key in url_params will be implicitly used as the reverse_lookup value.	None
distinct	bool	Parameter passed through to count_related().	False
display_field	str	Name of the field to use when displaying an object rather than just a count. This will be passed to hyperlinked_object() as the field parameter If not specified, it will use the "display" field.	'display'
**kwargs	dict	As the parent Column class.	{}

Examples:

class VLANTable(..., BaseTable):
    ...
    location_count = LinkedCountColumn(
        # Link for N related locations will be reverse("dcim:location_list") + "?vlans=<record.pk>"
        viewname="dcim:location_list",
        url_params={"vlans": "pk"},
        verbose_name="Locations",
    )

class CloudNetworkTable(BaseTable):
    ...
    circuit_count = LinkedCountColumn(
        # Link for N related circuits will be reverse("circuits:circuit_list") + "?cloud_network=<record.name>"
        viewname="circuits:circuit_list",
        url_params={"cloud_network": "name"},
        # `reverse_lookup` is rooted on Circuit (the count model); it drives
        # .annotate(circuit_count=count_related(Circuit, "circuit_terminations__cloud_network", distinct=True))
        reverse_lookup="circuit_terminations__cloud_network",
        # `lookup` is the nested lookup rooted on CloudNetwork, used to display the single related circuit
        lookup="circuit_terminations__circuit",
        distinct=True,
        display_field="cid",
        verbose_name="Circuits",
    )

counted_relation(model)

The name of model's own relation to the objects this column counts, or None if it is not one field.

A count column stands in for a relation: PrefixTable.vrf_count counts what Prefix.vrfs holds. That makes the relation the natural thing to carry in the column's place where a count itself cannot be carried -- an export, whose queryset has no annotate() behind the count.

Returns None unless the relation is a single field of model, which rules out a count reached through an intermediate model (CloudNetworkTable.circuit_count, via circuit terminations) or through the static group association machinery (dynamic_group_count): there is then no one relation for a column to hold.

nautobot.apps.tables.RelationshipColumn

Bases: Column

Display relationship association instances in the appropriate format.

nautobot.apps.tables.RoleTableMixin

Bases: BaseTable

Mixin to add a role field to a table.

nautobot.apps.tables.StatusTableMixin

Bases: BaseTable

Mixin to add a status field to a table.

nautobot.apps.tables.TableExtension

Template class for extending Tables.

An app can override the default columns for a table by either: - Extending the original default columns to include custom columns. - add_to_default_columns = ("my_app_name_new_column",) - Removing native columns from the default columns. - remove_from_default_columns = ("tenant",)

alter_queryset(queryset) classmethod

Alter the View class QuerySet.

This is a good place to add prefetch_related to the view queryset. example: return queryset.prefetch_related("my_model_set")

nautobot.apps.tables.TagColumn

Bases: TemplateColumn

Display a list of tags assigned to the object.

nautobot.apps.tables.ToggleColumn

Bases: CheckBoxColumn

Extend CheckBoxColumn to add a "toggle all" checkbox in the column header.