netbox-interface-name-rules 1.2.1__tar.gz → 1.2.3__tar.gz

{netbox_interface_name_rules-1.2.1/netbox_interface_name_rules.egg-info → netbox_interface_name_rules-1.2.3}/PKG-INFO

@@ -1,12 +1,21 @@
 Metadata-Version: 2.4
 Name: netbox-interface-name-rules
-Version: 1.2.1
+Version: 1.2.3
 Summary: NetBox plugin for automatic interface renaming when modules are installed
+Author: Marcin Zieba
 License-Expression: Apache-2.0
+Project-URL: Homepage, https://marcinpsk.github.io/netbox-InterfaceNameRules-plugin/
+Project-URL: Repository, https://github.com/marcinpsk/netbox-InterfaceNameRules-plugin
+Project-URL: Issues, https://github.com/marcinpsk/netbox-InterfaceNameRules-plugin/issues
+Project-URL: Documentation, https://marcinpsk.github.io/netbox-InterfaceNameRules-plugin/
+Project-URL: Changelog, https://github.com/marcinpsk/netbox-InterfaceNameRules-plugin/blob/main/CHANGELOG.md
+Keywords: netbox,plugin,dcim,interface,naming,modules,transceiver,automation
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Framework :: Django
+Classifier: Environment :: Plugins
+Classifier: Topic :: System :: Networking
 Requires-Python: >=3.12.0
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -22,6 +31,7 @@ Dynamic: license-file
 [![Python](https://img.shields.io/pypi/pyversions/netbox-interface-name-rules)](https://pypi.org/project/netbox-interface-name-rules/)
 [![NetBox](https://img.shields.io/badge/NetBox-%E2%89%A54.2.0-blue)](https://github.com/netbox-community/netbox)
 [![Contributors](https://img.shields.io/github/contributors/marcinpsk/netbox-InterfaceNameRules-plugin)](https://github.com/marcinpsk/netbox-InterfaceNameRules-plugin/graphs/contributors)
+[![REUSE status](https://api.reuse.software/badge/github.com/marcinpsk/netbox-InterfaceNameRules-plugin)](https://api.reuse.software/info/github.com/marcinpsk/netbox-InterfaceNameRules-plugin)
 
 Automatic interface renaming when modules are installed into NetBox device bays.
 
@@ -63,6 +73,24 @@ Add to `configuration.py`:
 PLUGINS = ['netbox_interface_name_rules']
 ```
 
+## Configuration
+
+Rules are managed through the NetBox UI under **Plugins → Interface Name Rules**, or via the REST API at `/api/plugins/interface-name-rules/rules/`.
+
+See the [full configuration guide](https://marcinpsk.github.io/netbox-InterfaceNameRules-plugin/configuration/) for all rule fields, priority scoring, and template variable reference.
+
+## Screenshots
+<p align="center">
+  <img src="https://raw.githubusercontent.com/marcinpsk/netbox-InterfaceNameRules-plugin/main/docs/icon.svg" alt="NetBox Interface Name Rules" width="30"/>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/marcinpsk/netbox-InterfaceNameRules-plugin/main/docs/screenshots/01-rule-list.png" alt="Rule list" width="700"/>
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/marcinpsk/netbox-InterfaceNameRules-plugin/main/docs/screenshots/11-apply-rule-preview.png" alt="Apply-rules preview" width="700"/>
+</p>
+
 ## Compatibility
 
 - NetBox ≥ 4.2.0

netbox_interface_name_rules-1.2.1/PKG-INFO → netbox_interface_name_rules-1.2.3/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: netbox-interface-name-rules
-Version: 1.2.1
-Summary: NetBox plugin for automatic interface renaming when modules are installed
-License-Expression: Apache-2.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Framework :: Django
-Requires-Python: >=3.12.0
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
 # NetBox Interface Name Rules Plugin
 
 [![PyPI](https://img.shields.io/pypi/v/netbox-interface-name-rules)](https://pypi.org/project/netbox-interface-name-rules/)
@@ -22,6 +8,7 @@ Dynamic: license-file
 [![Python](https://img.shields.io/pypi/pyversions/netbox-interface-name-rules)](https://pypi.org/project/netbox-interface-name-rules/)
 [![NetBox](https://img.shields.io/badge/NetBox-%E2%89%A54.2.0-blue)](https://github.com/netbox-community/netbox)
 [![Contributors](https://img.shields.io/github/contributors/marcinpsk/netbox-InterfaceNameRules-plugin)](https://github.com/marcinpsk/netbox-InterfaceNameRules-plugin/graphs/contributors)
+[![REUSE status](https://api.reuse.software/badge/github.com/marcinpsk/netbox-InterfaceNameRules-plugin)](https://api.reuse.software/info/github.com/marcinpsk/netbox-InterfaceNameRules-plugin)
 
 Automatic interface renaming when modules are installed into NetBox device bays.
 
@@ -63,6 +50,24 @@ Add to `configuration.py`:
 PLUGINS = ['netbox_interface_name_rules']
 ```
 
+## Configuration
+
+Rules are managed through the NetBox UI under **Plugins → Interface Name Rules**, or via the REST API at `/api/plugins/interface-name-rules/rules/`.
+
+See the [full configuration guide](https://marcinpsk.github.io/netbox-InterfaceNameRules-plugin/configuration/) for all rule fields, priority scoring, and template variable reference.
+
+## Screenshots
+<p align="center">
+  <img src="https://raw.githubusercontent.com/marcinpsk/netbox-InterfaceNameRules-plugin/main/docs/icon.svg" alt="NetBox Interface Name Rules" width="30"/>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/marcinpsk/netbox-InterfaceNameRules-plugin/main/docs/screenshots/01-rule-list.png" alt="Rule list" width="700"/>
+</p>
+<p align="center">
+  <img src="https://raw.githubusercontent.com/marcinpsk/netbox-InterfaceNameRules-plugin/main/docs/screenshots/11-apply-rule-preview.png" alt="Apply-rules preview" width="700"/>
+</p>
+
 ## Compatibility
 
 - NetBox ≥ 4.2.0

{netbox_interface_name_rules-1.2.1 → netbox_interface_name_rules-1.2.3}/netbox_interface_name_rules/__init__.py

@@ -2,7 +2,7 @@
 # Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
 from netbox.plugins import PluginConfig
 
-__version__ = "1.2.1"
+__version__ = "1.2.3"
 
 
 class InterfaceNameRulesConfig(PluginConfig):
@@ -16,6 +16,8 @@ class InterfaceNameRulesConfig(PluginConfig):
     min_version = "4.2.0"
     required_settings = []
     default_settings = {}
+    author = "Marcin Zieba"
+    author_email = "marcinpsk@gmail.com"
 
     def ready(self):
         """Connect signal handlers after all apps are loaded."""

{netbox_interface_name_rules-1.2.1 → netbox_interface_name_rules-1.2.3}/netbox_interface_name_rules/api/serializers.py

@@ -1,8 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
-from rest_framework import serializers
-
 from netbox.api.serializers import NetBoxModelSerializer
+from rest_framework import serializers
 
 from netbox_interface_name_rules.models import InterfaceNameRule
 
@@ -43,25 +42,25 @@ class InterfaceNameRuleSerializer(NetBoxModelSerializer):
 
         if is_device_level:
             # Device-level rules must not have a module_type FK
-            if module_type:
+            if module_type:  # pragma: no cover  # model.clean() runs first
                 raise serializers.ValidationError(
                     {"module_type": "Module type must be empty for device-level interface rules."}
                 )
         elif is_regex:
-            if not pattern:
+            if not pattern:  # pragma: no cover  # model.clean() runs first
                 raise serializers.ValidationError(
                     {"module_type_pattern": "Regex pattern is required when regex mode is enabled."}
                 )
-            if module_type:
+            if module_type:  # pragma: no cover  # model.clean() runs first
                 raise serializers.ValidationError(
                     {"module_type": "Cannot set both module_type and module_type_pattern. Choose one."}
                 )
         else:
-            if not module_type:
+            if not module_type:  # pragma: no cover  # model.clean() runs first
                 raise serializers.ValidationError(
                     {"module_type": "module_type is required when regex mode is disabled."}
                 )
-            if pattern:
+            if pattern:  # pragma: no cover  # model.clean() runs first
                 raise serializers.ValidationError(
                     {"module_type_pattern": "Cannot set module_type_pattern when regex mode is disabled."}
                 )

{netbox_interface_name_rules-1.2.1 → netbox_interface_name_rules-1.2.3}/netbox_interface_name_rules/engine.py

@@ -10,7 +10,8 @@ import ast
 import logging
 import re
 
-from django.db import transaction
+from django.core.exceptions import ValidationError
+from django.db import IntegrityError, transaction
 from django.db.models.functions import Length
 
 logger = logging.getLogger(__name__)
@@ -128,7 +129,7 @@ def _try_rename_device_interface(rule, iface, vc_position, device, renamed_pks):
 
     try:
         new_name = evaluate_name_template(rule.name_template, variables)
-    except Exception:
+    except (ValueError, TypeError, re.error):
         logger.exception(
             "Failed to evaluate template %r for interface %s (rule %s)",
             rule.name_template,
@@ -144,7 +145,7 @@ def _try_rename_device_interface(rule, iface, vc_position, device, renamed_pks):
     iface.name = new_name
     try:
         iface.full_clean()
-    except Exception:
+    except ValidationError:
         logger.exception(
             "Validation failed for device interface %s → %s (rule %s, device %s)",
             old_name,
@@ -156,7 +157,7 @@ def _try_rename_device_interface(rule, iface, vc_position, device, renamed_pks):
         return False
     try:
         iface.save()
-    except Exception:
+    except (IntegrityError, ValidationError):
         logger.exception(
             "DB save failed for device interface %s → %s (rule %s, device %s)",
             old_name,
@@ -401,7 +402,7 @@ def _resolve_bay_position(module_bay):
         digits = _extract_trailing_digits(module_bay.name)
         bay_position = digits if digits else "0"
     digits = _extract_trailing_digits(bay_position)
-    bay_position_num = digits if digits else bay_position
+    bay_position_num = digits if digits else "0"
     return bay_position, bay_position_num
 
 
@@ -524,6 +525,8 @@ def _find_channel_base(rule, ifaces, variables):
     _apply_rule_to_interface exactly ONCE per module for channel rules, preventing
     duplicate-name IntegrityErrors when channels already exist.
     """
+    if not ifaces:
+        return None
     for iface in ifaces:
         vars_copy = dict(variables)
         vars_copy["base"] = iface.name
@@ -568,7 +571,7 @@ def has_applicable_interfaces(rule) -> bool:
     try:
         results, _ = find_interfaces_for_rule(rule, limit=1)
         return len(results) > 0
-    except Exception:
+    except (ValueError, re.error):
         return False
 
 
@@ -608,6 +611,8 @@ def _evaluate_plain_interface(rule, module, iface, variables) -> dict | None:
 def _channel_rule_entry(rule, module, ifaces, variables) -> dict | None:
     """Return a result dict if the channel rule would change any name for this module, else None."""
     base_iface = _find_channel_base(rule, ifaces, variables)
+    if base_iface is None:
+        return None
     vars_copy = {**variables, "base": base_iface.name}
     expected_names = []
     try:
@@ -680,6 +685,8 @@ def find_interfaces_for_rule(rule, limit=None):
     If *limit* is set the list is truncated after that many changed entries, but
     *total_checked* always reflects the full count of interfaces examined.
     """
+    from collections import defaultdict
+
     from dcim.models import Interface
 
     module_qs = _build_module_qs(rule).select_related(
@@ -693,13 +700,18 @@ def find_interfaces_for_rule(rule, limit=None):
     )
     process_fn = _process_channel_module if rule.channel_count > 0 else _process_plain_module
 
-    processed_pks = []
+    # Batch-load all interfaces for matching modules to avoid N+1 queries.
+    ifaces_by_module = defaultdict(list)
+    for iface in Interface.objects.filter(module__in=module_qs).order_by("module_id", "name"):
+        ifaces_by_module[iface.module_id].append(iface)
+
+    processed_pks = set()
     results = []
     total_checked = 0
     for module in module_qs:
-        processed_pks.append(module.pk)
+        processed_pks.add(module.pk)
         variables = build_variables(module.module_bay, device=module.device)
-        ifaces = list(Interface.objects.filter(module=module).order_by("name"))
+        ifaces = ifaces_by_module.get(module.pk, [])
         checked, stop = process_fn(rule, module, ifaces, variables, limit, results, module_qs, processed_pks)
         total_checked += checked
         if stop:
@@ -726,6 +738,8 @@ def apply_rule_to_existing(rule, limit=None, interface_ids=None):
 
     Returns the number of interfaces renamed/created.
     """
+    from collections import defaultdict
+
     from dcim.models import Interface
 
     id_set = frozenset(interface_ids) if interface_ids is not None else None
@@ -737,15 +751,20 @@ def apply_rule_to_existing(rule, limit=None, interface_ids=None):
 
     module_qs = _build_module_qs(rule)
 
+    # Batch-load interfaces to avoid N+1 queries in the module loop.
+    ifaces_by_module = defaultdict(list)
+    for iface in Interface.objects.filter(module__in=module_qs).order_by("module_id", "name"):
+        ifaces_by_module[iface.module_id].append(iface)
+
     count = 0
     for module in module_qs.select_related("module_bay", "module_type", "device", "device__virtual_chassis"):
         variables = build_variables(module.module_bay, device=module.device)
+        ifaces = ifaces_by_module.get(module.pk, [])
 
         if rule.channel_count > 0:
             # Channel rule: process module ONCE using the best base interface.
             # Calling _apply_rule_to_interface for each existing interface would
             # attempt to create the same channel names multiple times.
-            ifaces = list(Interface.objects.filter(module=module).order_by("name"))
             if not ifaces:
                 continue
             base_iface = _find_channel_base(rule, ifaces, variables)
@@ -755,7 +774,7 @@ def apply_rule_to_existing(rule, limit=None, interface_ids=None):
             vars_copy["base"] = base_iface.name
             try:
                 count += _apply_rule_to_interface(rule, base_iface, vars_copy, module)
-            except Exception:
+            except (ValueError, ValidationError, IntegrityError):
                 logger.exception(
                     "Failed to apply channel rule '%s' to module '%s' (id=%s); skipping.",
                     rule,
@@ -763,14 +782,14 @@ def apply_rule_to_existing(rule, limit=None, interface_ids=None):
                     module.pk,
                 )
         else:
-            for iface in list(Interface.objects.filter(module=module).order_by("name")):
+            for iface in ifaces:
                 if id_set is not None and iface.pk not in id_set:
                     continue
                 vars_copy = dict(variables)
                 vars_copy["base"] = iface.name
                 try:
                     count += _apply_rule_to_interface(rule, iface, vars_copy, module)
-                except Exception:
+                except (ValueError, ValidationError, IntegrityError):
                     logger.exception(
                         "Failed to apply rule '%s' to interface '%s' (id=%s); skipping.",
                         rule,
@@ -831,5 +850,4 @@ def evaluate_name_template(template: str, variables: dict) -> str:
         except (SyntaxError, TypeError) as e:
             raise ValueError(f"Invalid arithmetic expression '{expr}': {e}") from e
 
-    result = re.sub(r"\{([^}]+)\}", _eval_expr, result)
-    return result
+    return re.sub(r"\{([^}]+)\}", _eval_expr, result)

{netbox_interface_name_rules-1.2.1 → netbox_interface_name_rules-1.2.3}/netbox_interface_name_rules/filters.py

@@ -53,7 +53,7 @@ class InterfaceNameRuleFilterSet(NetBoxModelFilterSet):
 
     def search(self, queryset, name, value):
         """Filter by pattern, template, description, or module type model name."""
-        return queryset.filter(
+        return queryset.select_related("module_type").filter(
             Q(module_type_pattern__icontains=value)
             | Q(name_template__icontains=value)
             | Q(description__icontains=value)

{netbox_interface_name_rules-1.2.1 → netbox_interface_name_rules-1.2.3}/netbox_interface_name_rules/models.py

@@ -9,7 +9,6 @@ from django.urls import reverse
 from netbox.models import NetBoxModel
 from taggit.managers import TaggableManager
 
-
 _REDOS_PATTERN = re.compile(r"(\+\*|\*\+|\?\?|\)\s*[\+\*\?]\s*[\+\*\?]|\)\s*\{[^{}]+\}\s*[\+\*\?])")
 
 

{netbox_interface_name_rules-1.2.1 → netbox_interface_name_rules-1.2.3}/netbox_interface_name_rules/signals.py

@@ -37,6 +37,7 @@ def on_module_pre_save(sender, instance, **kwargs):
         old = sender.objects.filter(pk=instance.pk).values("module_type_id").first()
         instance._prev_module_type_id = old["module_type_id"] if old else None
     except Exception:
+        logger.warning("Failed to capture previous module_type_id for Module pk=%s", instance.pk, exc_info=True)
         instance._prev_module_type_id = None
 
 
@@ -141,6 +142,7 @@ def on_device_pre_save(sender, instance, **kwargs):
         instance._prev_virtual_chassis_id = old["virtual_chassis_id"] if old else None
         instance._prev_vc_position = old["vc_position"] if old else None
     except Exception:
+        logger.warning("Failed to capture previous VC state for Device pk=%s", instance.pk, exc_info=True)
         instance._prev_virtual_chassis_id = None
         instance._prev_vc_position = None
 

netbox_interface_name_rules-1.2.3/netbox_interface_name_rules/templates/netbox_interface_name_rules/interfacenamerule.html

@@ -0,0 +1,115 @@
+{# SPDX-License-Identifier: Apache-2.0 #}
+{# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com> #}
+{% extends 'generic/object.html' %}
+{% load helpers %}
+{% load plugins %}
+
+{% block extra_controls %}
+  <a href="{% url 'plugins:netbox_interface_name_rules:interfacenamerule_test' %}?rule_id={{ object.pk }}"
+     class="btn btn-outline-secondary">
+    <i class="mdi mdi-flask-outline me-1"></i>Test in Build Rule
+  </a>
+  {% if perms.netbox_interface_name_rules.add_interfacenamerule %}
+    <a href="{% url 'plugins:netbox_interface_name_rules:interfacenamerule_duplicate' object.pk %}"
+       class="btn btn-success">
+      <i class="mdi mdi-content-copy me-1"></i>Duplicate
+    </a>
+  {% endif %}
+{% endblock extra_controls %}
+
+{% block content %}
+{# ── Priority callout ───────────────────────────────────────────────────────── #}
+<div class="alert alert-info d-flex align-items-start mb-3" role="alert">
+  <i class="mdi mdi-information-outline me-2 mt-1 fs-5"></i>
+  <div>
+    <strong>Priority score: {{ object.specificity_score }}</strong>
+    <span class="text-muted ms-1">({{ object.specificity_label }})</span>
+    <br>
+    <small>
+      This score is <em>auto-computed</em> — you cannot set it directly.
+      It controls which rule wins when multiple rules match the same module.
+      <strong>Higher score = higher priority.</strong>
+      Exact FK rules always outrank regex rules (score 1000+&nbsp;vs max ≤&nbsp;955).
+      Among regex rules, adding scope fields raises the score:
+      <code>parent_module_type</code>&nbsp;+4×100,
+      <code>device_type</code>&nbsp;+2×100,
+      <code>platform</code>&nbsp;+1×100,
+      plus pattern length.
+      <a data-bs-toggle="collapse" href="#priority-detail" class="ms-1">More…</a>
+    </small>
+    <div class="collapse mt-2" id="priority-detail">
+      <table class="table table-sm table-bordered mb-0 small">
+        <thead class="table-light"><tr><th>Rule type</th><th>Score formula</th><th>Range</th></tr></thead>
+        <tbody>
+          <tr><td>Exact FK (module_type)</td><td>1000 + scope</td><td>1000 – 1007</td></tr>
+          <tr><td>Regex (module_type_pattern)</td><td>scope × 100 + len(pattern)</td><td>0 – 955</td></tr>
+        </tbody>
+      </table>
+      <p class="small mb-0 mt-1">
+        Scope bits: <code>parent_module_type</code>=4, <code>device_type</code>=2, <code>platform</code>=1.
+        Two rules with the same score: lowest <code>pk</code> (oldest rule) wins.
+      </p>
+    </div>
+  </div>
+</div>
+
+<div class="row mb-3">
+  <div class="col col-md-12">
+    <div class="card">
+      <table class="table table-hover attr-table">
+        <thead>
+          <tr>
+            <th>Module Type</th>
+            <th>Parent Module Type</th>
+            <th>Device Type</th>
+            <th>Platform</th>
+            <th>Name Template</th>
+            <th>Channels</th>
+            <th>Channel Start</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>
+              {% if object.module_type_is_regex %}
+                <code>{{ object.module_type_pattern }}</code>
+                <span class="badge text-bg-info">regex</span>
+              {% elif object.module_type %}
+                <a href="{{ object.module_type.get_absolute_url }}">{{ object.module_type }}</a>
+              {% else %}
+                <span class="text-muted">—</span>
+              {% endif %}
+            </td>
+            <td>
+              {% if object.parent_module_type %}
+                <a href="{{ object.parent_module_type.get_absolute_url }}">{{ object.parent_module_type }}</a>
+              {% else %}
+                <span class="text-muted">Any parent</span>
+              {% endif %}
+            </td>
+            <td>
+              {% if object.device_type %}
+                <a href="{{ object.device_type.get_absolute_url }}">{{ object.device_type }}</a>
+              {% else %}
+                <span class="text-muted">Any device</span>
+              {% endif %}
+            </td>
+            <td>
+              {% if object.platform %}
+                <a href="{{ object.platform.get_absolute_url }}">{{ object.platform }}</a>
+              {% else %}
+                <span class="text-muted">Any platform</span>
+              {% endif %}
+            </td>
+            <td><code>{{ object.name_template }}</code></td>
+            <td>{{ object.channel_count|default:"—" }}</td>
+            <td>{{ object.channel_start }}</td>
+            <td>{{ object.description|default:"—" }}</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  </div>
+</div>
+{% endblock %}

netbox_interface_name_rules-1.2.3/netbox_interface_name_rules/templates/netbox_interface_name_rules/interfacenamerule_list.html

@@ -0,0 +1,164 @@
+{# SPDX-License-Identifier: Apache-2.0 #}
+{# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com> #}
+{% extends 'generic/object_list.html' %}
+
+{% block content %}
+    <div class="card mb-3" id="interface-name-rules-help">
+        <div class="card-header" role="button" tabindex="0" style="cursor: pointer;"
+             id="rules-help-header" aria-expanded="true" aria-controls="rules-help-body"
+             onclick="toggleRulesHelp()"
+             onkeydown="if(event.key==='Enter'||event.key===' '){toggleRulesHelp();event.preventDefault();}">
+            <h5 class="card-title mb-0 d-flex align-items-center">
+                <i class="mdi mdi-information-outline me-2"></i>
+                Interface Name Rules Reference
+                <i class="mdi ms-auto" id="rules-help-chevron"></i>
+            </h5>
+        </div>
+        <div id="rules-help-body" class="card-body">
+            <p>Define post-install interface rename rules for module types where NetBox's
+               position-based naming can't produce the correct interface name.</p>
+            <p>Covers <strong>converter offset</strong> (e.g., CVR-X2-SFP + GLC-T),
+               <strong>breakout transceivers</strong> (e.g., QSFP+ 4x10G with channel numbering),
+               <strong>platform-specific naming</strong> (e.g., Juniper et-/xe-/ge- prefixes),
+               and <strong>Virtual Chassis device port renaming</strong> (e.g., Gi0/1 → Gi2/1 on VC member 2).</p>
+
+            <p><strong>Signal-driven:</strong> Rules run automatically via two Django signals:</p>
+            <ul>
+                <li><code>post_save</code> on <strong>Module</strong> — fires after a module is installed into a device bay (primary path for transceiver/linecard naming).</li>
+                <li><code>post_save</code> on <strong>Device</strong> — fires after VC position changes (<code>vc_position</code> or <code>virtual_chassis</code> modified); triggers device-level interface renaming for VC members.</li>
+            </ul>
+            <p>Both paths use <code>on_commit</code> deferred execution so that all interfaces are in the database before renaming begins.</p>
+
+            <p><strong>Device interface rules</strong> (<code>Applies to Device Interfaces</code> checkbox) target native device-type interfaces
+               (<code>module=None</code>) rather than module-installed interfaces. Use these to rename VC member ports when the device
+               joins a stack or changes position. The <code>Module Type Pattern</code> field acts as an interface-name filter (regex) instead of a module type selector.</p>
+
+            <h6 class="mt-3">Supported Template Variables</h6>
+            <table class="table table-sm table-bordered" style="max-width: 750px;">
+                <thead>
+                    <tr><th style="width: 200px;">Variable</th><th>Rule type</th><th>Description</th></tr>
+                </thead>
+                <tbody>
+                    <tr><td><code>{slot}</code></td><td>Module</td><td>Top-level slot/module bay position (from grandparent or parent)</td></tr>
+                    <tr><td><code>{bay_position}</code></td><td>Module</td><td>Position of the bay this module is installed into (raw, e.g., "swp1")</td></tr>
+                    <tr><td><code>{bay_position_num}</code></td><td>Module</td><td>Numeric suffix of bay position (e.g., "swp1" &rarr; "1")</td></tr>
+                    <tr><td><code>{parent_bay_position}</code></td><td>Module</td><td>Position of the parent module's bay</td></tr>
+                    <tr><td><code>{sfp_slot}</code></td><td>Module</td><td>Numeric sub-bay index within the parent module</td></tr>
+                    <tr><td><code>{base}</code></td><td>Both</td><td>Original interface name from the template (or current name for device-level rules)</td></tr>
+                    <tr><td><code>{port}</code></td><td>Device</td><td>Segment after the last "/" in the current interface name (e.g., "Gi0/1" &rarr; "1"); full name if no "/"</td></tr>
+                    <tr><td><code>{channel}</code></td><td>Module</td><td>Breakout channel number (iterated from Ch. Start to Ch. Start + Channels - 1)</td></tr>
+                    <tr><td><code>{vc_position}</code></td><td>Both</td><td>Virtual Chassis member position (<code>device.vc_position</code>); requires device to be in a VC</td></tr>
+                </tbody>
+            </table>
+
+            <h6 class="mt-3">Arithmetic Expressions</h6>
+            <p>Arithmetic is supported inside braces:
+               <code>{8 + ({parent_bay_position} - 1) * 2 + {sfp_slot}}</code></p>
+
+            <h6 class="mt-3">Examples</h6>
+            <ul class="mb-0">
+                <li><strong>Converter offset:</strong> GLC-T in CVR-X2-SFP &rarr;
+                    <code>GigabitEthernet{slot}/{8 + ({parent_bay_position} - 1) * 2 + {sfp_slot}}</code></li>
+                <li><strong>Breakout:</strong> QSFP-4X10G-LR &rarr; <code>{base}:{channel}</code>
+                    (Channels=4, Ch. Start=0)</li>
+                <li><strong>Platform naming:</strong> QSFP-100G-LR4 on ACX7024 &rarr;
+                    <code>et-0/0/{bay_position}</code> (scoped via Parent Device Type)</li>
+                <li><strong>UfiSpace breakout:</strong> QSFP-100G-LR4 on S9610-36D &rarr;
+                    <code>swp{bay_position_num}s{channel}</code> (Channels=2, Ch. Start=1)</li>
+                <li><strong>Virtual Chassis linecard:</strong> VC-LINECARD on stack member &rarr;
+                    <code>Gi{vc_position}/{bay_position_num}</code> (requires device to be in a Virtual Chassis)</li>
+                <li><strong>VC device ports (Cisco):</strong> GigabitEthernet1/0/3 on stack member 2 &rarr;
+                    <code>GigabitEthernet{vc_position}/0/{port}</code> &rarr; GigabitEthernet2/0/3
+                    (device-level rule, pattern <code>GigabitEthernet\d+/\d+/\d+</code>)</li>
+                <li><strong>VC device ports (Juniper):</strong> ge-0/0/2 on VC member 1 &rarr;
+                    <code>ge-{vc_position}/0/{port}</code> &rarr; ge-1/0/2
+                    (device-level rule, pattern <code>ge-\d+/\d+/\d+</code>)</li>
+                <li><strong>VC device ports (Arista):</strong> Ethernet1/3 on VC member 2 &rarr;
+                    <code>Ethernet{vc_position}/{port}</code> &rarr; Ethernet2/3
+                    (device-level rule, pattern <code>Ethernet\d+/\d+</code>)</li>
+            </ul>
+
+            {% if supports_module_path %}
+            <div class="alert alert-success mt-3 mb-0">
+                <i class="mdi mdi-check-circle me-1"></i>
+                <strong><code>{module_path}</code> supported:</strong>
+                Platform naming rules (e.g., <code>et-0/0/{bay_position}</code>)
+                may be replaceable by using <code>{module_path}</code> in module type interface templates directly.
+                Converter offset and breakout rules are still needed.
+            </div>
+            {% else %}
+            <div class="alert alert-warning mt-3 mb-0">
+                <i class="mdi mdi-information-outline me-1"></i>
+                <strong><code>{module_path}</code> not available:</strong>
+                Platform naming rules
+                (e.g., Juniper <code>et-0/0/{bay_position}</code>) are required for correct interface naming.
+                Upgrade NetBox to get native <code>{module_path}</code> support.
+            </div>
+            {% endif %}
+        </div>
+    </div>
+    <script>
+        function toggleRulesHelp() {
+            const body = document.getElementById('rules-help-body');
+            const header = document.getElementById('rules-help-header');
+            const chevron = document.getElementById('rules-help-chevron');
+            const collapsed = body.style.display === 'none';
+            body.style.display = collapsed ? '' : 'none';
+            chevron.className = collapsed ? 'mdi ms-auto mdi-chevron-up' : 'mdi ms-auto mdi-chevron-down';
+            header.setAttribute('aria-expanded', collapsed ? 'true' : 'false');
+            localStorage.setItem('rulesHelpCollapsed', collapsed ? '' : '1');
+        }
+        document.addEventListener('DOMContentLoaded', function() {
+            const collapsed = localStorage.getItem('rulesHelpCollapsed') === '1';
+            const body = document.getElementById('rules-help-body');
+            const header = document.getElementById('rules-help-header');
+            const chevron = document.getElementById('rules-help-chevron');
+            body.style.display = collapsed ? 'none' : '';
+            chevron.className = collapsed ? 'mdi ms-auto mdi-chevron-down' : 'mdi ms-auto mdi-chevron-up';
+            header.setAttribute('aria-expanded', collapsed ? 'false' : 'true');
+
+            // AJAX toggle: click handler on toggle buttons (no form — avoids nested-form 405 bug)
+            document.addEventListener('click', function(e) {
+                const btn = e.target.closest('.toggle-btn[data-toggle-url]');
+                if (!btn) return;
+                const url = btn.dataset.toggleUrl;
+                const csrfToken =
+                    document.querySelector('input[name="csrfmiddlewaretoken"]')?.value ||
+                    (document.cookie.match(/(?:^|;\s*)csrftoken=([^;]+)/) || [])[1] || '';
+                btn.disabled = true;
+                fetch(url, {
+                    method: 'POST',
+                    headers: {'X-Requested-With': 'XMLHttpRequest', 'X-CSRFToken': csrfToken},
+                    credentials: 'same-origin',
+                }).then(r => {
+                    if (!r.ok) throw new Error('HTTP ' + r.status);
+                    return r.json();
+                }).then(data => {
+                    btn.disabled = false;
+                    const row = btn.closest('tr');
+                    if (data.enabled) {
+                        btn.className = 'btn btn-sm btn-success toggle-btn';
+                        btn.title = 'Enabled — click to disable';
+                        btn.setAttribute('aria-pressed', 'true');
+                        btn.setAttribute('aria-label', 'Enabled — click to disable');
+                        const iconOn = btn.querySelector('i');
+                        if (iconOn) iconOn.className = 'mdi mdi-check';
+                        if (row) row.classList.remove('text-muted', 'opacity-50');
+                    } else {
+                        btn.className = 'btn btn-sm btn-secondary toggle-btn';
+                        btn.title = 'Disabled — click to enable';
+                        btn.setAttribute('aria-pressed', 'false');
+                        btn.setAttribute('aria-label', 'Disabled — click to enable');
+                        const iconOff = btn.querySelector('i');
+                        if (iconOff) iconOff.className = 'mdi mdi-minus';
+                        if (row) row.classList.add('text-muted', 'opacity-50');
+                    }
+                }).catch(() => {
+                    btn.disabled = false;
+                    window.location.reload();
+                });
+            });
+        });
+    </script>
+    {{ block.super }}
+{% endblock %}