nautobot 2.0.0a2__py3-none-any.whl → 2.0.0b1__py3-none-any.whl

nautobot/docs/rest-api/ui-related-endpoints.md

@@ -0,0 +1,9 @@
+# UI Related API Endpoints
+
++++ 2.0.0
+
+Nautobot now retrieves its UI component information from API endpoints.
+
+!!!important
+    These UI-related API endpoints serve a very different purpose from the rest. While we encourage users to utilize other API endpoints whenever possilbe in custom development, these API endpoints are not for external users and for internal use only. Therefore, they are not subject to Semantic Versioning and can change at any time to fit Nautobot UI needs until we decide that we are ready to support UI specific endpoints.
+    Note that these API endpoints are hidden from OpenAPI schema as well.

nautobot/extras/admin.py

@@ -36,14 +36,13 @@ class FileProxyAdmin(NautobotModelAdmin):
 
 
 #
-# Job results (jobs, scripts, reports, Git repository sync, etc.)
+# Job results (jobs and Git repository sync)
 #
 
 
 @admin.register(JobResult)
 class JobResultAdmin(NautobotModelAdmin):
     list_display = [
-        "obj_type",
         "name",
         "date_created",
         "date_done",
@@ -51,14 +50,13 @@ class JobResultAdmin(NautobotModelAdmin):
         "status",
     ]
     fields = [
-        "obj_type",
+        "id",
         "name",
         "date_created",
         "date_done",
         "user",
         "status",
-        "data",
-        "task_id",
+        "result",
     ]
     list_filter = [
         "status",

nautobot/extras/api/customfields.py

@@ -1,11 +1,9 @@
 from django.contrib.contenttypes.models import ContentType
+
 from drf_spectacular.types import OpenApiTypes
 from drf_spectacular.utils import extend_schema_field
-from rest_framework.serializers import SerializerMethodField
-from rest_framework.fields import CreateOnlyDefault, Field
+from rest_framework.fields import Field
 
-from nautobot.core.api import ValidatedModelSerializer
-from nautobot.core.utils.deprecation import class_deprecated_in_favor_of
 from nautobot.extras.models import CustomField
 
 
@@ -42,52 +40,30 @@ class CustomFieldDefaultValues:
 
 @extend_schema_field(OpenApiTypes.OBJECT)
 class CustomFieldsDataField(Field):
-    def _get_custom_fields(self):
+    @property
+    def custom_field_keys(self):
         """
-        Cache CustomFields assigned to this model to avoid redundant database queries
+        Cache CustomField keys assigned to this model to avoid redundant database queries
         """
-        if not hasattr(self, "_custom_fields"):
+        if not hasattr(self, "_custom_field_keys"):
             content_type = ContentType.objects.get_for_model(self.parent.Meta.model)
-            self._custom_fields = CustomField.objects.filter(content_types=content_type)
-        return self._custom_fields
+            self._custom_field_keys = CustomField.objects.filter(content_types=content_type).values_list(
+                "key", flat=True
+            )
+        return self._custom_field_keys
 
     def to_representation(self, obj):
-        return {cf.key: obj.get(cf.key) for cf in self._get_custom_fields()}
+        return {key: obj.get(key) for key in self.custom_field_keys}
 
     def to_internal_value(self, data):
         """Support updates to individual fields on an existing instance without needing to provide the entire dict."""
 
+        # Discard any entries in data that do not align with actual CustomFields - this matches the REST API behavior
+        # for top-level serializer fields that do not exist or are not writable
+        data = {key: value for key, value in data.items() if key in self.custom_field_keys}
+
         # If updating an existing instance, start with existing _custom_field_data
         if self.parent.instance:
             data = {**self.parent.instance._custom_field_data, **data}
 
         return data
-
-
-class CustomFieldModelSerializerMixin(ValidatedModelSerializer):
-    """
-    Extends ModelSerializer to render any CustomFields and their values associated with an object.
-    """
-
-    computed_fields = SerializerMethodField(read_only=True)
-    custom_fields = CustomFieldsDataField(
-        source="_custom_field_data",
-        default=CreateOnlyDefault(CustomFieldDefaultValues()),
-    )
-
-    @extend_schema_field(OpenApiTypes.OBJECT)
-    def get_computed_fields(self, obj):
-        return obj.get_computed_fields()
-
-    def get_field_names(self, declared_fields, info):
-        """Ensure that "custom_fields" and "computed_fields" are always included appropriately."""
-        fields = list(super().get_field_names(declared_fields, info))
-        self.extend_field_names(fields, "custom_fields")
-        self.extend_field_names(fields, "computed_fields", opt_in_only=True)
-        return fields
-
-
-# TODO: remove in 2.2
-@class_deprecated_in_favor_of(CustomFieldModelSerializerMixin)
-class CustomFieldModelSerializer(CustomFieldModelSerializerMixin):
-    pass

nautobot/extras/api/fields.py

@@ -1,9 +1,6 @@
 from django.forms.fields import CallableChoiceIterator
 from rest_framework import serializers
 
-from nautobot.core.api.mixins import LimitQuerysetChoicesSerializerMixin
-from nautobot.extras.api.nested_serializers import NestedRoleSerializer, NestedStatusSerializer
-
 
 class MultipleChoiceJSONField(serializers.MultipleChoiceField):
     """A MultipleChoiceField that renders the received value as a JSON-compatible list rather than a set."""
@@ -18,11 +15,3 @@ class MultipleChoiceJSONField(serializers.MultipleChoiceField):
     def to_internal_value(self, data):
         set_value = super().to_internal_value(data)
         return sorted(set_value)
-
-
-class RoleSerializerField(LimitQuerysetChoicesSerializerMixin, NestedRoleSerializer):
-    """NestedSerializer field for `Role` object fields."""
-
-
-class StatusSerializerField(LimitQuerysetChoicesSerializerMixin, NestedStatusSerializer):
-    """NestedSerializer field for `Status` object fields."""

nautobot/extras/api/mixins.py

@@ -0,0 +1,45 @@
+import logging
+
+
+from nautobot.core.api import (
+    BaseModelSerializer,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TaggedModelSerializerMixin(BaseModelSerializer):
+    def get_field_names(self, declared_fields, info):
+        """Ensure that 'tags' field is always present except on nested serializers."""
+        fields = list(super().get_field_names(declared_fields, info))
+        if not self.is_nested:
+            self.extend_field_names(fields, "tags")
+        return fields
+
+    def create(self, validated_data):
+        tags = validated_data.pop("tags", None)
+        instance = super().create(validated_data)
+
+        if tags is not None:
+            return self._save_tags(instance, tags)
+        return instance
+
+    def update(self, instance, validated_data):
+        tags = validated_data.pop("tags", None)
+
+        # Cache tags on instance for change logging
+        instance._tags = tags or []
+
+        instance = super().update(instance, validated_data)
+
+        if tags is not None:
+            return self._save_tags(instance, tags)
+        return instance
+
+    def _save_tags(self, instance, tags):
+        if tags:
+            instance.tags.set([t.name for t in tags])
+        else:
+            instance.tags.clear()
+
+        return instance

nautobot/extras/api/relationships.py

@@ -1,20 +1,21 @@
 import logging
 
 from django.contrib.contenttypes.models import ContentType
-from django.core.exceptions import ValidationError as DjangoValidationError
 from django.db.models import Q
 from drf_spectacular.utils import extend_schema_field
-from rest_framework.exceptions import PermissionDenied
 from rest_framework.fields import JSONField
 from rest_framework.reverse import reverse
 from rest_framework.serializers import ValidationError
 
-from nautobot.core.api import ValidatedModelSerializer
 from nautobot.core.api.exceptions import SerializerNotFound
-from nautobot.core.api.utils import get_serializer_for_model
+from nautobot.core.api.mixins import WritableSerializerMixin
+from nautobot.core.api.utils import (
+    get_relation_info_for_nested_serializers,
+    get_serializer_for_model,
+    nested_serializer_factory,
+)
 from nautobot.extras.choices import RelationshipSideChoices
-from nautobot.extras.models import Relationship, RelationshipAssociation
-
+from nautobot.extras.models import Relationship
 
 logger = logging.getLogger(__name__)
 
@@ -39,15 +40,15 @@ side_data_schema = {
 
 @extend_schema_field(
     {
-        # Dictionary, keyed by relationship slug
+        # Dictionary, keyed by relationship key
         "type": "object",
         "additionalProperties": {
             "type": "object",
-            "required": ["id", "url", "name", "type"],
+            "required": ["id", "url", "label", "type"],
             "properties": {
                 "id": {"type": "string", "format": "uuid", "readOnly": True},
                 "url": {"type": "string", "format": "uri", "readOnly": True},
-                "name": {"type": "string", "readOnly": True},
+                "label": {"type": "string", "readOnly": True},
                 "type": {"type": "string", "readOnly": True, "example": "one-to-many"},
                 "source": {"type": "object", "properties": side_data_schema},
                 "destination": {"type": "object", "properties": side_data_schema},
@@ -56,7 +57,7 @@ side_data_schema = {
         },
     }
 )
-class RelationshipsDataField(JSONField):
+class RelationshipsDataField(WritableSerializerMixin, JSONField):
     """
     Represent the set of all Relationships defined for a given model,
     and all RelationshipAssociations per Relationship that apply to a specific instance of that model.
@@ -66,16 +67,18 @@ class RelationshipsDataField(JSONField):
     to provide the entire dict of all relationships and associations.
     """
 
+    queryset = None
+
     def to_representation(self, value):
         """
         Get a JSON representation of all relationships and associations applicable to this model.
 
         Returns:
             {
-                "<relationship-slug>": {
+                "<relationship_key>": {
                     "id": ...,
                     "url": ...,
-                    "name": ...,
+                    "label": ...,
                     "type": "one-to-one|one-to-many|many-to-many|...",
                     # if this model can be the destination of the relationship:
                     "source": {
@@ -96,7 +99,7 @@ class RelationshipsDataField(JSONField):
                         "objects": [{...}, {...}, ...],
                     },
                 },
-                "<relationship-slug>": {
+                "<relationship_key>": {
                     ...
                 },
                 ...
@@ -106,8 +109,9 @@ class RelationshipsDataField(JSONField):
         relationships_data = value.get_relationships(include_hidden=True)
         for this_side, relationships in relationships_data.items():
             for relationship, associations in relationships.items():
+                depth = int(self.context.get("depth", 0))
                 data.setdefault(
-                    relationship.slug,
+                    relationship.key,
                     {
                         "id": str(relationship.id),
                         "url": reverse(
@@ -115,42 +119,56 @@ class RelationshipsDataField(JSONField):
                             kwargs={"pk": relationship.id},
                             request=self.parent.context.get("request"),
                         ),
-                        "name": relationship.name,
+                        "label": relationship.label,
                         "type": relationship.type,
                     },
                 )
                 other_side = RelationshipSideChoices.OPPOSITE[this_side]
-                data[relationship.slug][other_side] = {"label": relationship.get_label(this_side)}
+                data[relationship.key][other_side] = {"label": relationship.get_label(this_side)}
 
                 other_type = getattr(relationship, f"{other_side}_type")
-                data[relationship.slug][other_side]["object_type"] = f"{other_type.app_label}.{other_type.model}"
+                data[relationship.key][other_side]["object_type"] = f"{other_type.app_label}.{other_type.model}"
 
                 # Get the nested serializer, if any, for the objects of other_type.
                 # This may fail, such as in the case of a plugin that has models but doesn't implement serializers,
                 # or in the case of a relationship involving models from a plugin that's not currently enabled.
                 other_side_serializer = None
                 other_side_model = other_type.model_class()
+
+                other_objects = [assoc.get_peer(value) for assoc in associations if assoc.get_peer(value) is not None]
                 if other_side_model is not None:
                     try:
-                        other_side_serializer = get_serializer_for_model(other_side_model, prefix="Nested")
+                        depth = int(self.context.get("depth", 0))
+                        if depth != 0:
+                            if associations and other_objects:
+                                relation_info = get_relation_info_for_nested_serializers(
+                                    associations[0], other_objects[0], f"{other_side}"
+                                )
+                                other_side_serializer, field_kwargs = self.build_nested_field(
+                                    f"{other_side}", relation_info, depth
+                                )
                     except SerializerNotFound:
                         pass
 
-                other_objects = [assoc.get_peer(value) for assoc in associations if assoc.get_peer(value) is not None]
-
                 if other_side_serializer is not None:
-                    data[relationship.slug][other_side]["objects"] = [
-                        other_side_serializer(other_obj, context=self.context).data for other_obj in other_objects
+                    data[relationship.key][other_side]["objects"] = [
+                        other_side_serializer(
+                            other_obj, context={"request": self.context.get("request")}, **field_kwargs
+                        ).data
+                        for other_obj in other_objects
                     ]
                 else:
                     # Simulate a serializer that contains nothing but the id field.
-                    data[relationship.slug][other_side]["objects"] = [
+                    data[relationship.key][other_side]["objects"] = [
                         {"id": other_obj.id} for other_obj in other_objects
                     ]
 
         logger.debug("to_representation(%s) -> %s", value, data)
         return data
 
+    def build_nested_field(self, field_name, relation_info, nested_depth):
+        return nested_serializer_factory(relation_info, nested_depth)
+
     def to_internal_value(self, data):
         """
         Allow for updates to some relationships without overriding others.
@@ -186,20 +204,20 @@ class RelationshipsDataField(JSONField):
                 output_data[relationship]["peer"] = []
 
         # Input validation - prevent referencing a relationship that doesn't exist or apply
-        relationship_slugs = [relationship.slug for relationship in relationships]
-        for relationship_slug in data:
-            if relationship_slug not in relationship_slugs:
+        relationship_keys = [relationship.key for relationship in relationships]
+        for relationship_key in data:
+            if relationship_key not in relationship_keys:
                 raise ValidationError(
-                    f'"{relationship_slug}" is not a relationship on {self.parent.Meta.model._meta.label}'
+                    f'"{relationship_key}" is not a relationship on {self.parent.Meta.model._meta.label}'
                 )
 
         for relationship in relationships:
-            if relationship.slug not in data:
+            if relationship.key not in data:
                 # No changes to any associations for this relationship, can disregard it
                 del output_data[relationship]
                 continue
 
-            relationship_data = data[relationship.slug]
+            relationship_data = data[relationship.key]
 
             for other_side in ["source", "destination", "peer"]:
                 if other_side not in relationship_data:
@@ -218,7 +236,7 @@ class RelationshipsDataField(JSONField):
                 # Don't allow omitting 'objects' altogether as a shorthand for deleting all associations
                 if "objects" not in relationship_data[other_side]:
                     raise ValidationError(
-                        f'"objects" must be specified under ["{relationship.slug}"]["{other_side}"] when present'
+                        f'"objects" must be specified under ["{relationship.key}"]["{other_side}"] when present'
                     )
                 objects_data = relationship_data[other_side]["objects"]
                 if not isinstance(objects_data, (list, tuple)):
@@ -237,145 +255,31 @@ class RelationshipsDataField(JSONField):
                 # Object lookup time!
                 other_type = getattr(relationship, f"{other_side}_type")
                 other_side_model = other_type.model_class()
+                self.queryset = other_side_model.objects
                 other_side_serializer = None
                 if other_side_model is None:
                     raise ValidationError(f"Model {other_type} is not currently installed, cannot look it up")
                 try:
-                    other_side_serializer = get_serializer_for_model(other_side_model, prefix="Nested")
+                    other_side_serializer = get_serializer_for_model(other_side_model)
                 except SerializerNotFound as exc:
                     raise ValidationError(
                         f"No Nested{other_side_model}Serializer found, cannot deserialize it"
                     ) from exc
 
-                for object_data in objects_data:
-                    serializer_instance = other_side_serializer(data=object_data, context=self.context)
-                    # may raise ValidationError, let it bubble up if so
-                    serializer_instance.is_valid()
+                depth = int(self.context.get("depth", 0))
 
-                    # We don't check/enforce relationship source_filter/destination_filter here, as that'll be handled
-                    # later by `RelationshipAssociation.validated_save()` in RelationshipModelSerializerMixin.
-                    output_data[relationship][other_side].append(serializer_instance.data)
+                if depth != 0:
+                    for object_data in objects_data:
+                        serializer_instance = other_side_serializer(data=object_data, context=self.context)
+                        # may raise ValidationError, let it bubble up if so
+                        serializer_instance.is_valid(raise_exception=True)
 
+                        # We don't check/enforce relationship source_filter/destination_filter here, as that'll be handled
+                        # later by `RelationshipAssociation.validated_save()` in RelationshipModelSerializerMixin.
+                        output_data[relationship][other_side].append(serializer_instance.data)
+                else:
+                    for object_data in objects_data:
+                        instance = super().to_internal_value(object_data)
+                        output_data[relationship][other_side].append({"id": instance.id})
         logger.debug("to_internal_value(%s) -> %s", data, output_data)
         return {self.field_name: output_data}
-
-
-class RelationshipModelSerializerMixin(ValidatedModelSerializer):
-    """Extend ValidatedModelSerializer with a `relationships` field."""
-
-    relationships = RelationshipsDataField(required=False, source="*")
-
-    def create(self, validated_data):
-        relationships_data = validated_data.pop("relationships", {})
-        required_relationships_errors = self.Meta().model.required_related_objects_errors(
-            output_for="api", initial_data=relationships_data
-        )
-        if required_relationships_errors:
-            raise ValidationError({"relationships": required_relationships_errors})
-        instance = super().create(validated_data)
-        if relationships_data:
-            try:
-                self._save_relationships(instance, relationships_data)
-            except DjangoValidationError as error:
-                raise ValidationError(str(error))
-        return instance
-
-    def update(self, instance, validated_data):
-        relationships_key_specified = "relationships" in self.context["request"].data
-        relationships_data = validated_data.pop("relationships", {})
-        required_relationships_errors = self.Meta().model.required_related_objects_errors(
-            output_for="api",
-            initial_data=relationships_data,
-            relationships_key_specified=relationships_key_specified,
-            instance=instance,
-        )
-        if required_relationships_errors:
-            raise ValidationError({"relationships": required_relationships_errors})
-
-        instance = super().update(instance, validated_data)
-        if relationships_data:
-            self._save_relationships(instance, relationships_data)
-        return instance
-
-    def _save_relationships(self, instance, relationships):
-        """Create/update RelationshipAssociations corresponding to a model instance."""
-        # relationships has already passed RelationshipsDataField.to_internal_value(), so we can skip some try/excepts
-        logger.debug("_save_relationships: %s : %s", instance, relationships)
-        for relationship, relationship_data in relationships.items():
-
-            for other_side in ["source", "destination", "peer"]:
-                if other_side not in relationship_data:
-                    continue
-
-                other_type = getattr(relationship, f"{other_side}_type")
-                other_side_model = other_type.model_class()
-                other_side_serializer = get_serializer_for_model(other_side_model, prefix="Nested")
-                serializer_instance = other_side_serializer(context={"request": self.context.get("request")})
-
-                expected_objects_data = relationship_data[other_side]
-                expected_objects = [
-                    serializer_instance.to_internal_value(object_data) for object_data in expected_objects_data
-                ]
-
-                this_side = RelationshipSideChoices.OPPOSITE[other_side]
-
-                if this_side != RelationshipSideChoices.SIDE_PEER:
-                    existing_associations = relationship.relationship_associations.filter(
-                        **{f"{this_side}_id": instance.pk}
-                    )
-                    existing_objects = [assoc.get_peer(instance) for assoc in existing_associations]
-                else:
-                    existing_associations_1 = relationship.relationship_associations.filter(source_id=instance.pk)
-                    existing_objects_1 = [assoc.get_peer(instance) for assoc in existing_associations_1]
-                    existing_associations_2 = relationship.relationship_associations.filter(destination_id=instance.pk)
-                    existing_objects_2 = [assoc.get_peer(instance) for assoc in existing_associations_2]
-                    existing_associations = list(existing_associations_1) + list(existing_associations_2)
-                    existing_objects = existing_objects_1 + existing_objects_2
-
-                add_objects = []
-                remove_assocs = []
-
-                for obj, assoc in zip(existing_objects, existing_associations):
-                    if obj not in expected_objects:
-                        remove_assocs.append(assoc)
-                for obj in expected_objects:
-                    if obj not in existing_objects:
-                        add_objects.append(obj)
-
-                for add_object in add_objects:
-                    if "request" in self.context and not self.context["request"].user.has_perm(
-                        "extras.add_relationshipassociation"
-                    ):
-                        raise PermissionDenied("This user does not have permission to create RelationshipAssociations.")
-                    if other_side != RelationshipSideChoices.SIDE_SOURCE:
-                        assoc = RelationshipAssociation(
-                            relationship=relationship,
-                            source_type=relationship.source_type,
-                            source_id=instance.id,
-                            destination_type=relationship.destination_type,
-                            destination_id=add_object.id,
-                        )
-                    else:
-                        assoc = RelationshipAssociation(
-                            relationship=relationship,
-                            source_type=relationship.source_type,
-                            source_id=add_object.id,
-                            destination_type=relationship.destination_type,
-                            destination_id=instance.id,
-                        )
-                    assoc.validated_save()  # enforce relationship filter logic, etc.
-                    logger.debug("Created %s", assoc)
-
-                for remove_assoc in remove_assocs:
-                    if "request" in self.context and not self.context["request"].user.has_perm(
-                        "extras.delete_relationshipassociation"
-                    ):
-                        raise PermissionDenied("This user does not have permission to delete RelationshipAssociations.")
-                    logger.debug("Deleting %s", remove_assoc)
-                    remove_assoc.delete()
-
-    def get_field_names(self, declared_fields, info):
-        """Ensure that "relationships" is always included as an opt-in field."""
-        fields = list(super().get_field_names(declared_fields, info))
-        self.extend_field_names(fields, "relationships", opt_in_only=True)
-        return fields