netbox-scope-switcher 0.1.0__py3-none-any.whl

netbox_scope_switcher/__init__.py

@@ -0,0 +1,33 @@
+from netbox.plugins import PluginConfig
+
+
+class ScopeSwitcherConfig(PluginConfig):
+    name = 'netbox_scope_switcher'
+    verbose_name = 'Scope Switcher'
+    description = ('Adds a configurable, multi-dimension scope selector to the top '
+                   'navbar. Selecting values scopes list views by tenant, site, '
+                   'region, tag, and any other filter you configure.')
+    version = '0.1.0'
+    author = 'Du10777'
+    base_url = 'scope-switcher'
+    min_version = '4.4.0'
+    # Request-scoped filtering of list views by the selected scope values.
+    middleware = ['netbox_scope_switcher.middleware.ScopeSwitcherMiddleware']
+    # Defaults to a single tenant scope so the out-of-the-box behaviour matches
+    # netbox-tenant-switcher; override `scopes`/`mode` in PLUGINS_CONFIG.
+    default_settings = {
+        'scopes': [
+            {'param': 'tenant_id', 'model': 'tenancy.Tenant'},
+        ],
+        'mode': 'redirect',
+    }
+
+    def ready(self):
+        super().ready()
+        # Fail fast at startup with a clear message on a bad configuration,
+        # rather than raising a 500 somewhere in the request path.
+        from .config import validate_config
+        validate_config()
+
+
+config = ScopeSwitcherConfig

netbox_scope_switcher/applicability.py

@@ -0,0 +1,53 @@
+"""
+Introspection: which configured scope params apply to a given request's view.
+
+A scope applies to a page only if the page is an object *list* view whose
+filterset declares a filter named after the scope's ``param``. Filter coverage
+differs a lot across NetBox models, so applicability is computed *per scope*
+(a prefixes list may support ``tenant_id`` and ``tag`` but not ``region_id``).
+"""
+from netbox.views.generic import ObjectListView
+
+from .config import get_scopes
+
+
+def _filterset_params(view_class):
+    """Set of filter names a list view's filterset exposes, or None if it has none."""
+    filterset = getattr(view_class, 'filterset', None)
+    if filterset is None:
+        return None
+
+    getter = getattr(filterset, 'get_filters', None)
+    if callable(getter):
+        try:
+            return set(getter().keys())
+        except Exception:
+            pass
+
+    params = set()
+    for attr in ('base_filters', 'declared_filters'):
+        params |= set(getattr(filterset, attr, {}) or {})
+    return params or None
+
+
+def list_view_params(request):
+    """
+    Return the set of filter param names available on the current list view, or
+    None if the request does not resolve to an ``ObjectListView``.
+    """
+    match = getattr(request, 'resolver_match', None)
+    view_func = getattr(match, 'func', None) if match else None
+    view_class = getattr(view_func, 'view_class', None) if view_func else None
+    if view_class is None or not issubclass(view_class, ObjectListView):
+        return None
+    return _filterset_params(view_class)
+
+
+def applicable_params(request, scopes=None):
+    """Configured scope params that apply to the current page (possibly empty)."""
+    params = list_view_params(request)
+    if not params:
+        return set()
+    if scopes is None:
+        scopes = get_scopes()
+    return {s.param for s in scopes if s.param in params}

netbox_scope_switcher/cascade.py

@@ -0,0 +1,199 @@
+"""
+Cascading option filtering.
+
+When values are selected in some scopes, the option lists of the *other* scopes
+are narrowed to the objects consistent with that selection -- e.g. picking a
+Tenant limits Regions to the regions where that tenant has sites, and limits
+Sites/Racks to that tenant's, while picking a Region limits Tenants to those
+present in it.
+
+Two passes, both reusing NetBox's own filtersets (which encode every relationship
+including tree descendants):
+
+- forward: filter the target's own queryset by every other scope its filterset
+  supports (the "downward" direction -- Site by Region, Rack by Location, ...).
+- reverse: for the scopes the target's filterset can't express (the "upward"
+  direction -- Region by Tenant, Tenant Group by Tenant, ...), pivot through a
+  bridge model that has a FK to the target and whose filterset does support the
+  source (Site bridges Region<->Tenant; Tenant bridges TenantGroup<->Tenant).
+"""
+import importlib
+
+from django.http import QueryDict
+
+from .config import get_scopes
+
+NULL = 'null'
+_FS_CACHE = {}
+_FILTERS_CACHE = {}
+
+
+def filterset_for(model):
+    """Resolve ``<app>.filtersets.<Model>FilterSet`` (cached), or None."""
+    label = model._meta.label
+    if label not in _FS_CACHE:
+        fs = None
+        try:
+            module = importlib.import_module('{}.filtersets'.format(model._meta.app_label))
+            fs = getattr(module, '{}FilterSet'.format(model.__name__), None)
+        except Exception:
+            fs = None
+        _FS_CACHE[label] = fs
+    return _FS_CACHE[label]
+
+
+def _get_filters(fs):
+    """Filterset's filters dict (cached; filtersets are static per class)."""
+    if fs is None:
+        return {}
+    cached = _FILTERS_CACHE.get(fs)
+    if cached is None:
+        try:
+            cached = fs.get_filters()
+        except Exception:
+            cached = {}
+        _FILTERS_CACHE[fs] = cached
+    return cached
+
+
+def _model_of(filt):
+    qs = getattr(filt, 'queryset', None)
+    return getattr(qs, 'model', None) if qs is not None else None
+
+
+def _resolve_param(target_filters, source):
+    """The param on the target filterset that filters by the source scope's model."""
+    exact = target_filters.get(source.param)
+    if exact is not None and _model_of(exact) is source.model:
+        return source.param
+    candidates = [
+        name for name, filt in target_filters.items()
+        if _model_of(filt) is source.model and not (name.endswith('__n') or name.endswith('__any'))
+    ]
+    for name in candidates:
+        if name.endswith('_id'):
+            return name
+    return candidates[0] if candidates else None
+
+
+def _apply_filterset(fs, qs, param_values):
+    if not param_values:
+        return qs
+    data = QueryDict(mutable=True)
+    for param, values in param_values.items():
+        data.setlist(param, [str(v) for v in values])
+    try:
+        return fs(data, queryset=qs).qs
+    except Exception:
+        return qs
+
+
+def _restricted(model, user):
+    manager = model.objects
+    restrict = getattr(manager, 'restrict', None)
+    if user is not None and callable(restrict):
+        return restrict(user, 'view')
+    return manager.all()
+
+
+def _fk_field_to(model, target_model):
+    """Name of a FK/O2O field on ``model`` pointing at ``target_model`` (prefer a
+    real relation over a denormalised ``_prefixed`` one), or None."""
+    best = None
+    for f in model._meta.get_fields():
+        if not (getattr(f, 'many_to_one', False) or getattr(f, 'one_to_one', False)):
+            continue
+        if not getattr(f, 'concrete', False):
+            continue
+        if getattr(f, 'related_model', None) is target_model:
+            name = f.name
+            if not name.startswith('_'):
+                return name
+            best = best or name
+    return best
+
+
+def _forward(scope, qs, selection, scopes):
+    fs = filterset_for(scope.model)
+    filters = _get_filters(fs)
+    applied = set()
+    if not filters:
+        return qs, applied
+    param_values = {}
+    for source in scopes:
+        if source.param == scope.param:
+            continue
+        values = selection.get(source.param)
+        if not values:
+            continue
+        param = _resolve_param(filters, source)
+        if param:
+            param_values[param] = values
+            applied.add(source.param)
+    if param_values:
+        qs = _apply_filterset(fs, qs, param_values)
+    return qs, applied
+
+
+def _reverse(scope, qs, selection, remaining, user, scopes):
+    """Narrow ``qs`` by the ``remaining`` sources via bridge models (FK -> target)."""
+    scope_models = {s.model for s in scopes}
+    allowed = None
+    for bridge in scope_models:
+        if bridge is scope.model:
+            continue
+        fk_name = _fk_field_to(bridge, scope.model)
+        if not fk_name:
+            continue
+        bridge_filters = _get_filters(filterset_for(bridge))
+        # The bridge can express a source either via a model-typed filter, or --
+        # if the bridge *is* the source's model -- by filtering on identity.
+        if not any(s.model is bridge or _resolve_param(bridge_filters, s) for s in remaining):
+            continue
+
+        bqs = _restricted(bridge, user)
+        param_values = {}
+        for source in scopes:
+            values = selection.get(source.param)
+            if not values:
+                continue
+            if source.model is bridge:
+                field = 'pk' if source.value_field == 'pk' else source.value_field
+                concrete = [v for v in values
+                            if v != NULL and (source.value_field != 'pk' or v.isdigit())]
+                if concrete:
+                    bqs = bqs.filter(**{'{}__in'.format(field): concrete})
+            else:
+                param = _resolve_param(bridge_filters, source)
+                if param:
+                    param_values[param] = values
+        if param_values:
+            bqs = _apply_filterset(filterset_for(bridge), bqs, param_values)
+
+        ids = set(bqs.values_list(fk_name, flat=True))
+        ids.discard(None)
+        allowed = ids if allowed is None else (allowed | ids)
+
+    if allowed is not None:
+        qs = qs.filter(pk__in=allowed)
+    return qs
+
+
+def constrained_queryset(scope, qs, selection, user=None, scopes=None):
+    """
+    Narrow ``qs`` (already permission-restricted) to objects consistent with the
+    values selected in the OTHER scopes. Only ever narrows; returns ``qs``
+    unchanged when nothing applies. Pass ``scopes`` to avoid re-resolving them.
+    """
+    if not selection:
+        return qs
+    if scopes is None:
+        scopes = get_scopes()
+    qs, applied = _forward(scope, qs, selection, scopes)
+    remaining = [
+        s for s in scopes
+        if s.param != scope.param and selection.get(s.param) and s.param not in applied
+    ]
+    if remaining:
+        qs = _reverse(scope, qs, selection, remaining, user, scopes)
+    return qs

netbox_scope_switcher/config.py

@@ -0,0 +1,144 @@
+"""
+Scope configuration: parse and validate the ``scopes`` setting, resolve each
+scope's model, and expose the resolved list to the rest of the plugin.
+
+A *scope* is one filter dimension the switcher can apply -- tenant, site,
+region, tag, ... Each is described by a dict in ``PLUGINS_CONFIG``::
+
+    {"param": "tenant_id", "model": "tenancy.Tenant", "label": "Tenant",
+     "value_field": "pk"}
+
+Defaults to a single tenant scope, so out-of-the-box behaviour matches the
+original ``netbox-tenant-switcher`` plugin.
+"""
+from django.apps import apps
+from django.conf import settings
+from django.core.exceptions import FieldDoesNotExist, ImproperlyConfigured
+from django.utils.text import capfirst
+
+PLUGIN_NAME = 'netbox_scope_switcher'
+
+# Out-of-the-box behaviour == netbox-tenant-switcher: scope by tenant only.
+DEFAULT_SCOPES = [
+    {'param': 'tenant_id', 'model': 'tenancy.Tenant'},
+]
+DEFAULT_MODE = 'redirect'
+VALID_MODES = ('redirect', 'silent')
+
+
+class Scope:
+    """A single resolved scope dimension."""
+
+    __slots__ = ('param', 'model', 'label', 'value_field', 'group')
+
+    def __init__(self, param, model, label=None, value_field='pk', group=None):
+        self.param = param
+        self.value_field = value_field or 'pk'
+        self.group = group or None
+        self.model = _resolve_model(param, model)
+        if self.value_field != 'pk':
+            _check_field(self.model, self.value_field, param)
+        # No explicit label -> use NetBox's own (translated) model name, so the
+        # section titles follow the active UI language. Resolved per request
+        # (get_scopes() rebuilds scopes each call).
+        self.label = label or capfirst(self.model._meta.verbose_name)
+
+    @property
+    def order_field(self):
+        for f in ('name', self.value_field, 'slug'):
+            if _has_field(self.model, f):
+                return f
+        return 'pk'
+
+    def display(self, obj):
+        return getattr(obj, 'name', None) or str(obj)
+
+    def value_of(self, obj):
+        raw = obj.pk if self.value_field == 'pk' else getattr(obj, self.value_field)
+        return str(raw)
+
+    def queryset(self, user):
+        """Options the user is allowed to see, ordered for display."""
+        manager = self.model.objects
+        restrict = getattr(manager, 'restrict', None)
+        qs = restrict(user, 'view') if callable(restrict) else manager.all()
+        return qs.order_by(self.order_field)
+
+
+def _plugin_settings():
+    return (getattr(settings, 'PLUGINS_CONFIG', {}) or {}).get(PLUGIN_NAME, {}) or {}
+
+
+def _resolve_model(param, label):
+    try:
+        return apps.get_model(label)
+    except (ValueError, LookupError) as exc:
+        raise ImproperlyConfigured(
+            "netbox-scope-switcher: scope '{}' references unknown model '{}' "
+            "({}). Use 'app_label.ModelName'.".format(param, label, exc)
+        )
+
+
+def _has_field(model, name):
+    if name == 'pk':
+        return True
+    try:
+        model._meta.get_field(name)
+        return True
+    except FieldDoesNotExist:
+        return False
+
+
+def _check_field(model, name, param):
+    if not _has_field(model, name):
+        raise ImproperlyConfigured(
+            "netbox-scope-switcher: scope '{}' uses value_field '{}', which does "
+            "not exist on {}.".format(param, name, model._meta.label)
+        )
+
+
+def get_mode():
+    mode = _plugin_settings().get('mode', DEFAULT_MODE)
+    if mode not in VALID_MODES:
+        raise ImproperlyConfigured(
+            "netbox-scope-switcher: 'mode' must be one of {}, got {!r}.".format(
+                VALID_MODES, mode
+            )
+        )
+    return mode
+
+
+def get_scopes():
+    """Return the resolved list of :class:`Scope` objects for the current settings."""
+    raw = _plugin_settings().get('scopes', DEFAULT_SCOPES)
+    if not isinstance(raw, (list, tuple)):
+        raise ImproperlyConfigured("netbox-scope-switcher: 'scopes' must be a list of dicts.")
+
+    scopes = []
+    seen = set()
+    for entry in raw:
+        if not isinstance(entry, dict) or 'param' not in entry or 'model' not in entry:
+            raise ImproperlyConfigured(
+                "netbox-scope-switcher: each scope needs at least 'param' and "
+                "'model' keys; got {!r}.".format(entry)
+            )
+        param = entry['param']
+        if param in seen:
+            raise ImproperlyConfigured(
+                "netbox-scope-switcher: duplicate scope param '{}'.".format(param)
+            )
+        seen.add(param)
+        scopes.append(Scope(
+            param=param,
+            model=entry['model'],
+            label=entry.get('label'),
+            value_field=entry.get('value_field', 'pk'),
+            group=entry.get('group'),
+        ))
+    return scopes
+
+
+def validate_config():
+    """Validate settings at startup; raise ImproperlyConfigured on any problem."""
+    get_mode()
+    get_scopes()

netbox_scope_switcher/middleware.py

@@ -0,0 +1,87 @@
+"""
+Scope switcher middleware.
+
+When one or more scope values are selected (stored in the session), scope object
+*list* views by adding the corresponding filter params to the URL -- but only
+for the scopes whose filter the current list view actually supports, and only
+when the user hasn't already set that param by hand.
+
+- ``mode="redirect"`` (default): issue a single 302 to the same URL with the
+  params added, so the address bar and NetBox's own filter panel reflect the
+  scope, links are shareable, and "Clear filters" behaves predictably.
+- ``mode="silent"``: rewrite ``request.GET`` in place, without redirecting.
+
+Combining semantics:
+
+- several values within one scope -> OR (repeated param: ``?tenant_id=1&tenant_id=2``)
+- different scopes -> AND (naturally, they are different params)
+- the special ``null`` value -> ``?param=null`` (objects with no value assigned)
+
+The middleware only ever *narrows* a result set; NetBox object permissions still
+apply on top.
+"""
+from django.shortcuts import redirect
+
+from netbox.views.generic import ObjectListView
+
+from .applicability import _filterset_params
+from .config import get_mode, get_scopes
+from .views import SESSION_KEY, get_state
+
+
+class ScopeSwitcherMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        return self.get_response(request)
+
+    def process_view(self, request, view_func, view_args, view_kwargs):
+        if request.method != 'GET':
+            return None
+        # Never touch API / GraphQL / HTMX (partial) requests.
+        if request.headers.get('HX-Request'):
+            return None
+        path = request.path
+        if path.startswith('/api/') or path.startswith('/graphql'):
+            return None
+
+        session = getattr(request, 'session', None)
+        if session is None or SESSION_KEY not in session:
+            return None
+        scopes = get_scopes()
+        state = get_state(request, scopes)
+        if not state:
+            return None
+
+        view_class = getattr(view_func, 'view_class', None)
+        if view_class is None or not issubclass(view_class, ObjectListView):
+            return None
+        available = _filterset_params(view_class)
+        if not available:
+            return None
+
+        to_apply = {}
+        for scope in scopes:
+            values = state.get(scope.param)
+            if not values:
+                continue
+            # A manually chosen filter always wins (and this also breaks the
+            # redirect loop: once we add the param, it is present on reload).
+            if scope.param in request.GET:
+                continue
+            if scope.param not in available:
+                continue
+            to_apply[scope.param] = values
+
+        if not to_apply:
+            return None
+
+        params = request.GET.copy()
+        for param, values in to_apply.items():
+            params.setlist(param, values)
+
+        if get_mode() == 'silent':
+            request.GET = params
+            return None
+        return redirect('{}?{}'.format(path, params.urlencode()))