content: from dataclasses import dataclass
  from typing import Iterable
  
  from django.conf import settings
  from django.contrib.auth.mixins import AccessMixin
  from django.core.exceptions import ImproperlyConfigured
  from django.db.models import QuerySet
  from django.urls import reverse
  from django.urls.exceptions import NoReverseMatch
  from django.utils.translation import gettext_lazy as _
  
  from netbox.api.authentication import TokenAuthentication
  from netbox.plugins import PluginConfig
  from netbox.registry import registry
  from utilities.relations import get_related_models
  from utilities.request import safe_for_redirect
  from utilities.string import title
  from .permissions import resolve_permission
  
  __all__ = (
      'ConditionalLoginRequiredMixin',
      'ContentTypePermissionRequiredMixin',
      'GetRelatedModelsMixin',
      'GetReturnURLMixin',
      'ObjectPermissionRequiredMixin',
      'TokenConditionalLoginRequiredMixin',
      'ViewTab',
      'get_action_url',
      'get_viewname',
      'register_model_view',
  )
  
  
  #
  # View Mixins
  #
  
  class ConditionalLoginRequiredMixin(AccessMixin):
      """
      Similar to Django's LoginRequiredMixin, but enforces authentication only if LOGIN_REQUIRED is True.
      """
      def dispatch(self, request, *args, **kwargs):
          if settings.LOGIN_REQUIRED and not request.user.is_authenticated:
              return self.handle_no_permission()
          return super().dispatch(request, *args, **kwargs)
  
  
  class TokenConditionalLoginRequiredMixin(ConditionalLoginRequiredMixin):
      def dispatch(self, request, *args, **kwargs):
          # Attempt to authenticate the user using a DRF token, if provided
          if settings.LOGIN_REQUIRED and not request.user.is_authenticated:
              authenticator = TokenAuthentication()
              auth_info = authenticator.authenticate(request)
              if auth_info is not None:
                  request.user = auth_info[0]  # User object
                  request.auth = auth_info[1]
  
          return super().dispatch(request, *args, **kwargs)
  
  
  class ContentTypePermissionRequiredMixin(ConditionalLoginRequiredMixin):
      """
      Similar to Django's built-in PermissionRequiredMixin, but extended to check model-level permission assignments.
      This is related to ObjectPermissionRequiredMixin, except that it does not enforce object-level permissions,
      and fits within NetBox's custom permission enforcement system.
  
      additional_permissions: An optional iterable of statically declared permissions to evaluate in addition to those
                              derived from the object type
      """
      additional_permissions = list()
  
      def get_required_permission(self):
          """
          Return the specific permission necessary to perform the requested action on an object.
          """
          raise NotImplementedError(_("{self.__class__.__name__} must implement get_required_permission()").format(
              class_name=self.__class__.__name__
          ))
  
      def has_permission(self):
          user = self.request.user
          permission_required = self.get_required_permission()
  
          # Check that the user has been granted the required permission(s).
          if user.has_perms((permission_required, *self.additional_permissions)):
              return True
  
          return False
  
      def dispatch(self, request, *args, **kwargs):
          if not self.has_permission():
              return self.handle_no_permission()
  
          return super().dispatch(request, *args, **kwargs)
  
  
  class ObjectPermissionRequiredMixin(ConditionalLoginRequiredMixin):
      """
      Similar to Django's built-in PermissionRequiredMixin, but extended to check for both model-level and object-level
      permission assignments. If the user has only object-level permissions assigned, the view's queryset is filtered
      to return only those objects on which the user is permitted to perform the specified action.
  
      additional_permissions: An optional iterable of statically declared permissions to evaluate in addition to those
                              derived from the object type
      """
      additional_permissions = list()
  
      def get_required_permission(self):
          """
          Return the specific permission necessary to perform the requested action on an object.
          """
          raise NotImplementedError(_("{class_name} must implement get_required_permission()").format(
              class_name=self.__class__.__name__
          ))
  
      def has_permission(self):
          user = self.request.user
          permission_required = self.get_required_permission()
  
          # Check that the user has been granted the required permission(s).
          if user.has_perms((permission_required, *self.additional_permissions)):
  
              # Update the view's QuerySet to filter only the permitted objects
              action = resolve_permission(permission_required)[1]
              self.queryset = self.queryset.restrict(user, action)
  
              return True
  
          return False
  
      def dispatch(self, request, *args, **kwargs):
  
          if not hasattr(self, 'queryset'):
              raise ImproperlyConfigured(
                  _(
                      '{class_name} has no queryset defined. ObjectPermissionRequiredMixin may only be used on views '
                      'which define a base queryset'
                  ).format(class_name=self.__class__.__name__)
              )
  
          if not self.has_permission():
              return self.handle_no_permission()
  
          return super().dispatch(request, *args, **kwargs)
  
  
  class GetReturnURLMixin:
      """
      Provides logic for determining where a user should be redirected after processing a form.
      """
      default_return_url = None
  
      def get_return_url(self, request, obj=None):
  
          # First, see if `return_url` was specified as a query parameter or form data. Use this URL only if it's
          # considered safe.
          return_url = request.GET.get('return_url') or request.POST.get('return_url')
          if return_url and safe_for_redirect(return_url):
              return return_url
  
          # Next, check if the object being modified (if any) has an absolute URL.
          if obj is not None and obj.pk and hasattr(obj, 'get_absolute_url'):
              return obj.get_absolute_url()
  
          # Fall back to the default URL (if specified) for the view.
          if self.default_return_url is not None:
              return reverse(self.default_return_url)
  
          # Attempt to dynamically resolve the list view for the object
          if hasattr(self, 'queryset'):
              try:
                  return get_action_url(self.queryset.model, action='list')
              except NoReverseMatch:
                  pass
  
          # If all else fails, return home. Ideally this should never happen.
          return reverse('home')
  
  
  class GetRelatedModelsMixin:
      """
      Provides logic for collecting all related models for the currently viewed model.
      """
      @dataclass
      class RelatedObjectCount:
          queryset: QuerySet
          filter_param: str
          label: str = ''
  
          @property
          def name(self):
              return self.label or title(_(self.queryset.model._meta.verbose_name_plural))
  
      def get_related_models(self, request, instance, omit=None, extra=None):
          """
          Get related models of the view's `queryset` model without those listed in `omit`. Will be sorted alphabetical.
  
          Args:
              request: Current request being processed.
              instance: The instance related models should be looked up for. A list of instances can be passed to match
                  related objects in this list (e.g. to find sites of a region including child regions).
              omit: Remove relationships to these models from the result. Needs to be passed, if related models don't
                  provide a `_list` view.
              extra: Add extra models to the list of automatically determined related models. Can be used to add indirect
                  relationships.
          """
          omit = omit or []
          model = self.queryset.model
          related = filter(
              lambda m: m[0] is not model and m[0] not in omit,
              get_related_models(model, False)
          )
  
          related_models = [
              self.RelatedObjectCount(
                  model.objects.restrict(request.user, 'view').filter(**(
                      {f'{field}__in': instance}
                      if isinstance(instance, Iterable)
                      else {field: instance}
                  )),
                  f'{field}_id'
              )
              for model, field in related
          ]
          if extra is not None:
              related_models.extend([
                  self.RelatedObjectCount(*attrs) for attrs in extra
              ])
  
          return sorted(
              filter(lambda roc: roc.queryset.exists(), related_models),
              key=lambda roc: roc.name,
          )
  
  
  class ViewTab:
      """
      ViewTabs are used for navigation among multiple object-specific views, such as the changelog or journal for
      a particular object.
  
      Args:
          label: Human-friendly text
          visible: A callable which determines whether the tab should be displayed. This callable must accept exactly one
              argument: the object instance. If a callable is not specified, the tab's visibility will be determined by
              its badge (if any) and the value of `hide_if_empty`.
          badge: A static value or callable to display alongside the label (optional). If a callable is used, it must
              accept a single argument representing the object being viewed.
          weight: Numeric weight to influence ordering among other tabs (default: 1000)
          permission: The permission required to display the tab (optional).
          hide_if_empty: If true, the tab will be displayed only if its badge has a meaningful value. (This parameter is
              evaluated only if the tab is permitted to be displayed according to the `visible` parameter.)
      """
      def __init__(self, label, visible=None, badge=None, weight=1000, permission=None, hide_if_empty=False):
          self.label = label
          self.visible = visible
          self.badge = badge
          self.weight = weight
          self.permission = permission
          self.hide_if_empty = hide_if_empty
  
      def render(self, instance):
          """
          Return the attributes needed to render a tab in HTML if the tab should be displayed. Otherwise, return None.
          """
          if self.visible is not None and not self.visible(instance):
              return None
          badge_value = self._get_badge_value(instance)
          if self.badge and self.hide_if_empty and not badge_value:
              return None
          return {
              'label': self.label,
              'badge': badge_value,
              'weight': self.weight,
          }
  
      def _get_badge_value(self, instance):
          if not self.badge:
              return None
          if callable(self.badge):
              return self.badge(instance)
          return self.badge
  
  
  #
  # Utility functions
  #
  
  def get_viewname(model, action=None, rest_api=False):
      """
      Return the view name for the given model and action, if valid.
  
      :param model: The model or instance to which the view applies
      :param action: A string indicating the desired action (if any); e.g. "add" or "list"
      :param rest_api: A boolean indicating whether this is a REST API view
      """
      is_plugin = isinstance(model._meta.app_config, PluginConfig)
      app_label = model._meta.app_label
      model_name = model._meta.model_name
  
      if rest_api:
          viewname = f'{app_label}-api:{model_name}'
          if is_plugin:
              viewname = f'plugins-api:{viewname}'
          if action:
              viewname = f'{viewname}-{action}'
  
      else:
          viewname = f'{app_label}:{model_name}'
          if is_plugin:
              viewname = f'plugins:{viewname}'
          if action:
              viewname = f'{viewname}_{action}'
  
      return viewname
  
  
  def get_action_url(model, action=None, rest_api=False, kwargs=None):
      """
      Return the URL for the given model and action, if valid; otherwise raise NoReverseMatch.
      Will defer to _get_action_url() on the model if it exists.
  
      :param model: The model or instance to which the URL belongs
      :param action: A string indicating the desired action (if any); e.g. "add" or "list"
      :param rest_api: A boolean indicating whether this is a REST API action
      :param kwargs: A dictionary of keyword arguments for the view to include when resolving its URL path (optional)
      """
      if hasattr(model, '_get_action_url'):
          return model._get_action_url(action, rest_api, kwargs)
  
      return reverse(get_viewname(model, action, rest_api), kwargs=kwargs)
  
  
  def register_model_view(model, name='', path=None, detail=True, kwargs=None):
      """
      This decorator can be used to "attach" a view to any model in NetBox. This is typically used to inject
      additional tabs within a model's detail view. For example, to add a custom tab to NetBox's dcim.Site model:
  
          @register_model_view(Site, 'myview', path='my-custom-view')
          class MyView(ObjectView):
              ...
  
      This will automatically create a URL path for MyView at `/dcim/sites/<id>/my-custom-view/` which can be
      resolved using the view name `dcim:site_myview'.
  
      Args:
          model: The Django model class with which this view will be associated.
          name: The string used to form the view's name for URL resolution (e.g. via `reverse()`). This will be appended
              to the name of the base view for the model using an underscore. If blank, the model name will be used.
          path: The URL path by which the view can be reached (optional). If not provided, `name` will be used.
          detail: True if the path applied to an individual object; False if it attaches to the base (list) path.
          kwargs: A dictionary of keyword arguments for the view to include when registering its URL path (optional).
      """
      def _wrapper(cls):
          app_label = model._meta.app_label
          model_name = model._meta.model_name
  
          if model_name not in registry['views'][app_label]:
              registry['views'][app_label][model_name] = []
  
          registry['views'][app_label][model_name].append({
              'name': name,
              'view': cls,
              'path': path if path is not None else name,
              'detail': detail,
              'kwargs': kwargs or {},
          })
  
          return cls
  
      return _wrapper
  