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

nautobot/core/api/renderers.py

@@ -1,4 +1,16 @@
-from rest_framework.renderers import BrowsableAPIRenderer
+import csv
+from io import StringIO
+import json
+import logging
+
+from django.conf import settings
+from rest_framework.renderers import BaseRenderer, BrowsableAPIRenderer, JSONRenderer
+
+from nautobot.core.celery import NautobotKombuJSONEncoder
+from nautobot.core.models.constants import NATURAL_KEY_SLUG_SEPARATOR
+
+
+logger = logging.getLogger(__name__)
 
 
 class FormlessBrowsableAPIRenderer(BrowsableAPIRenderer):
@@ -6,8 +18,147 @@ class FormlessBrowsableAPIRenderer(BrowsableAPIRenderer):
     Override the built-in BrowsableAPIRenderer to disable HTML forms.
     """
 
-    def show_form_for_method(self, *args, **kwargs):
+    def show_form_for_method(self, view, method, request, obj):
+        """Returns True if a form should be shown for this method."""
+        if method == "OPTIONS":
+            return super().show_form_for_method(view, method, request, obj)
         return False
 
     def get_filter_form(self, data, view, request):
         return None
+
+
+class NautobotJSONRenderer(JSONRenderer):
+    """
+    Override the encoder_class of the default JSONRenderer to handle the rendering of TagsManager in Nautobot API.
+    """
+
+    encoder_class = NautobotKombuJSONEncoder
+
+
+class NautobotCSVRenderer(BaseRenderer):
+    """
+    Render to CSV format.
+
+    Loosely inspired by https://github.com/mjumbewu/django-rest-framework-csv/.
+    """
+
+    media_type = "text/csv"
+    format = "csv"
+    charset = "UTF-8"
+
+    def render(self, data, accepted_media_type=None, renderer_context=None):
+        """
+        Render the provided data to CSV format.
+        """
+        if not data:
+            return ""
+
+        # TODO need to handle rendering of exceptions (e.g. not authenticated) as those have a different data dict.
+        if isinstance(data, dict):
+            data = [data]
+
+        headers = self.get_headers(data)
+
+        buffer = StringIO()
+        writer = csv.writer(buffer)
+        writer.writerow(headers)
+        for record in data:
+            writer.writerow(
+                self.object_to_row_elements(
+                    record,
+                    headers=headers,
+                )
+            )
+
+        return buffer.getvalue()
+
+    @classmethod
+    def get_headers(cls, data):
+        """Identify the appropriate CSV headers corresponding to the given data."""
+        base_headers = list(data[0].keys())
+
+        # Remove specific headers that we know are irrelevant
+        for undesired_header in [
+            "computed_fields",
+            "custom_fields",  # will be handled later as a special case
+            "notes_url",  # irrelevant to CSV
+            "relationships",
+            "url",  # irrelevant to CSV
+        ]:
+            if undesired_header in base_headers:
+                base_headers.remove(undesired_header)
+
+        # Add individual headers for each relevant custom field
+        # Since we know there are cases where custom field data may be missing from a given instance,
+        # we iterate over *all* instances in the data set to be safe.
+        if "custom_fields" in data[0]:
+            cf_headers = set()
+            for record in data:
+                cf_headers |= {f"cf_{key}" for key in record["custom_fields"]}
+            cf_headers = sorted(cf_headers)
+        else:
+            cf_headers = []
+
+        # TODO: relationships? computed fields?
+
+        headers = base_headers + cf_headers
+
+        # Coerce important fields, if present, to the front of the list
+        for priority_header in ["id", "natural_key_slug", "display", "name"]:
+            if priority_header in headers:
+                headers.remove(priority_header)
+                headers.insert(0, priority_header)
+
+        return headers
+
+    def object_to_row_elements(self, record, *, headers):
+        """Given an object and the desired CSV headers, yield the serialized values for each header."""
+        for key in headers:
+            # Retrieve the base value corresponding to this key
+            if key.startswith("cf_"):
+                # Custom field
+                value = record.get("custom_fields", {}).get(key[3:], None)
+            else:
+                value = record.get(key)
+
+            # Coerce the value to a format to make the CSV renderer happy (i.e. a string or number)
+            if value is None:
+                # Unfortunately we're going to have to be a bit lossy here, as CSV doesn't have a distinction between
+                # a null value and an empty string value for a column.
+                # We could choose to represent a null value as "None" or "null" but those are also valid strings, so...
+                # See corresponding logic in NautobotCSVParser.
+                value = ""
+            elif isinstance(value, dict):
+                if "natural_key_slug" in value:
+                    # A nested related object
+                    if value.get("generic_foreign_key"):
+                        # A *generic* nested related object
+                        value = NATURAL_KEY_SLUG_SEPARATOR.join([value["object_type"], value["natural_key_slug"]])
+                    else:
+                        value = value["natural_key_slug"]
+                elif "value" in value and "label" in value:
+                    # An enum type
+                    value = value["value"]
+                else:
+                    value = json.dumps(value)
+            elif isinstance(value, (list, tuple, set)):
+                if isinstance(value, set):
+                    value = sorted(value)
+                if value and isinstance(value[0], dict) and "natural_key_slug" in value[0]:
+                    # Multiple nested related objects
+                    if value[0].get("generic_foreign_key"):
+                        # Multiple *generic* nested related obects
+                        value = [
+                            NATURAL_KEY_SLUG_SEPARATOR.join([v["object_type"], v["natural_key_slug"]]) for v in value
+                        ]
+                    else:
+                        value = [v["natural_key_slug"] for v in value]
+                # The below makes for better UX than `json.dump()` for most current cases.
+                value = ",".join([str(v) if v is not None else "" for v in value])
+            elif not isinstance(value, (str, int)):
+                value = str(value)
+
+            if settings.DEBUG:
+                logger.debug("key: %s, value: %s", key, value)
+            yield value

nautobot/core/api/schema.py

@@ -4,7 +4,7 @@ import re
 from drf_spectacular.contrib.django_filters import DjangoFilterExtension
 from drf_spectacular.extensions import OpenApiSerializerFieldExtension
 from drf_spectacular.openapi import AutoSchema
-from drf_spectacular.plumbing import build_array_type, build_media_type_object, is_serializer
+from drf_spectacular.plumbing import build_array_type, build_media_type_object, get_doc, is_serializer
 from drf_spectacular.serializers import PolymorphicProxySerializerExtension
 from rest_framework import serializers
 from rest_framework.relations import ManyRelatedField
@@ -54,6 +54,40 @@ class NautobotAutoSchema(AutoSchema):
             return None
         return super()._get_paginator()
 
+    def get_description(self):
+        """
+        Get the appropriate description for a given API endpoint.
+
+        By default, if a specific action doesn't have its own docstring, and neither does the view class,
+        drf-spectacular will walk up the MRO of the view class until it finds a docstring, and use that.
+        Most of our viewsets (for better or for worse) do not have docstrings, and so it'll find and use the generic
+        docstring of the `NautobotModelViewSet` class, which isn't very useful to the end user. Instead of doing that,
+        we only use the docstring of the view itself (ignoring its parent class docstrings), or if none exists, we
+        make an attempt at rendering a basically accurate default description.
+        """
+        action_or_method = getattr(self.view, getattr(self.view, "action", self.method.lower()), None)
+        action_doc = get_doc(action_or_method)
+        if action_doc:
+            return action_doc
+
+        if self.view.__doc__:
+            view_doc = get_doc(self.view.__class__)
+            if view_doc:
+                return view_doc
+
+        # Fall back to a generic default description
+        if hasattr(self.view, "queryset") and self.method.lower() in self.method_mapping:
+            action = self.method_mapping[self.method.lower()].replace("_", " ").capitalize()
+            model_name = self.view.queryset.model._meta.verbose_name
+            if action == "Create":
+                return f"{action} one or more {model_name} objects."
+            if "{id}" in self.path:
+                return f"{action} a {model_name} object."
+            return f"{action} a list of {model_name} objects."
+
+        # Give up
+        return super().get_description()
+
     def get_filter_backends(self):
         """Nautobot's custom bulk operations, even though they return a list of records, are NOT filterable."""
         if self.is_bulk_action:
@@ -84,7 +118,17 @@ class NautobotAutoSchema(AutoSchema):
             for param in operation["parameters"]:
                 if param["name"] == "id" and "description" not in param:
                     param["description"] = "Unique object identifier, either a UUID primary key or a natural-key slug."
-
+            if self.method == "GET":
+                if "depth" not in operation["parameters"]:
+                    operation["parameters"].append(
+                        {
+                            "in": "query",
+                            "name": "depth",
+                            "required": False,
+                            "description": "Serializer Depth",
+                            "schema": {"type": "integer", "minimum": 0, "maximum": 10, "default": 1},
+                        }
+                    )
         return operation
 
     def get_operation_id(self):