netbox-device-type-sync 1.0.0__py3-none-any.whl

netbox_device_type_sync/diff.py

@@ -0,0 +1,248 @@
+"""
+Compare a device with its device type.
+
+build_plan() returns a SyncPlan: the device fields that differ, and for each
+component type the components to create, the components whose properties
+differ, and the template names that clash with components of installed
+modules. Building a plan never changes the database.
+"""
+
+from dataclasses import dataclass, field
+
+from .components import (
+    COMPONENT_KINDS,
+    DEVICE_FIELDS,
+    EMPTY,
+    ComponentKind,
+    DeviceField,
+    SyncContext,
+    display_field,
+)
+
+__all__ = (
+    'ComponentDiff',
+    'DeviceFieldDiff',
+    'KindDiff',
+    'PropertyChange',
+    'PropertySummary',
+    'SyncPlan',
+    'TemplateToCreate',
+    'build_plan',
+)
+
+
+@dataclass
+class PropertyChange:
+    """A property of one component whose value differs from its template."""
+
+    current: str
+    desired: str
+
+
+@dataclass
+class ComponentDiff:
+    """A device component whose properties differ from its template."""
+
+    name: str
+    component: object
+    template: object
+    changes: dict  # property key -> PropertyChange
+
+
+@dataclass
+class TemplateToCreate:
+    """A template that has no component on the device."""
+
+    name: str
+    template: object
+
+
+@dataclass
+class Conflict:
+    """A template whose name is taken by a component of an installed module."""
+
+    name: str
+    component: object
+
+
+@dataclass
+class PropertySummary:
+    """A property and all the components of one type on which it differs."""
+
+    prop: object
+    label: str
+    selection_key: str
+    components: list  # (component name, PropertyChange)
+
+    @property
+    def count(self):
+        return len(self.components)
+
+
+@dataclass
+class KindDiff:
+    """The differences for one component type."""
+
+    kind: ComponentKind
+    create: list = field(default_factory=list)
+    update: list = field(default_factory=list)
+    conflicts: list = field(default_factory=list)
+
+    @property
+    def is_empty(self):
+        return not (self.create or self.update or self.conflicts)
+
+    @property
+    def property_summaries(self):
+        summaries = []
+        for prop in self.kind.properties:
+            components = [
+                (diff.name, diff.changes[prop.key])
+                for diff in self.update
+                if prop.key in diff.changes
+            ]
+            if components:
+                summaries.append(
+                    PropertySummary(
+                        prop=prop,
+                        label=str(prop.label(self.kind.component_model)),
+                        selection_key=f'{self.kind.key}.{prop.key}',
+                        components=components,
+                    )
+                )
+        return summaries
+
+
+@dataclass
+class DeviceFieldDiff:
+    """A device field whose value differs from the device type."""
+
+    field: DeviceField
+    label: str
+    selection_key: str
+    current: str
+    desired: str
+
+
+@dataclass
+class SyncPlan:
+    device: object
+    device_type: object
+    device_fields: list
+    kinds: list  # KindDiff for every component type, in COMPONENT_KINDS order
+
+    @property
+    def changed_kinds(self):
+        return [k for k in self.kinds if not k.is_empty]
+
+    @property
+    def create_count(self):
+        return sum(len(k.create) for k in self.kinds)
+
+    @property
+    def selection_keys(self):
+        """All the property keys the user can select."""
+        keys = [f.selection_key for f in self.device_fields]
+        for kind_diff in self.kinds:
+            keys.extend(s.selection_key for s in kind_diff.property_summaries)
+        return keys
+
+    @property
+    def is_empty(self):
+        return not self.device_fields and not self.changed_kinds
+
+
+def _diff_device_fields(device, device_type):
+    diffs = []
+    for device_field in DEVICE_FIELDS:
+        source = device_type._meta.get_field(device_field.source)
+        desired = getattr(device_type, source.attname)
+        current = getattr(device, device._meta.get_field(device_field.name).attname)
+        # Like Device.save(): an empty device type value is never copied
+        if desired in (None, '') or desired == current:
+            continue
+        diffs.append(
+            DeviceFieldDiff(
+                field=device_field,
+                label=str(device_field.label()),
+                selection_key=f'device.{device_field.key}',
+                current=display_field(device, device_field.name, current)
+                if current not in (None, '')
+                else EMPTY,
+                desired=display_field(device_type, device_field.source, desired),
+            )
+        )
+    return diffs
+
+
+def _template_key(kind, template, ctx):
+    if kind.key == 'inventoryitem':
+        return ctx.template_path(template)
+    return ctx.template_name(template)
+
+
+def _component_key(kind, component, ctx):
+    if kind.key == 'inventoryitem':
+        return ctx.component_path(component)
+    return component.name
+
+
+def _key_display(key):
+    return ' / '.join(key) if isinstance(key, tuple) else key
+
+
+def diff_kind(kind, device, ctx):
+    result = KindDiff(kind=kind)
+    templates = getattr(device.device_type, kind.template_accessor).all()
+    components = getattr(device, kind.component_accessor).all()
+
+    device_components = {}
+    module_components = {}
+    for component in components:
+        if kind.is_modular and component.module_id is not None:
+            module_components[component.name] = component
+        else:
+            device_components[_component_key(kind, component, ctx)] = component
+
+    for template in templates:
+        key = _template_key(kind, template, ctx)
+        name = _key_display(key)
+        component = device_components.get(key)
+        if component is None:
+            if key in module_components:
+                result.conflicts.append(
+                    Conflict(name=name, component=module_components[key])
+                )
+            else:
+                result.create.append(TemplateToCreate(name=name, template=template))
+            continue
+
+        changes = {}
+        for prop in kind.properties:
+            desired, desired_display = prop.read_template(template, ctx)
+            current, current_display = prop.read_component(component, ctx)
+            if desired != current:
+                changes[prop.key] = PropertyChange(
+                    current=current_display, desired=desired_display
+                )
+        if changes:
+            result.update.append(
+                ComponentDiff(
+                    name=name, component=component, template=template, changes=changes
+                )
+            )
+
+    return result
+
+
+def build_plan(device):
+    """
+    Compare the device with its device type and return a SyncPlan.
+    """
+    ctx = SyncContext(device)
+    return SyncPlan(
+        device=device,
+        device_type=device.device_type,
+        device_fields=_diff_device_fields(device, device.device_type),
+        kinds=[diff_kind(kind, device, ctx) for kind in COMPONENT_KINDS],
+    )

netbox_device_type_sync/forms.py

@@ -0,0 +1,35 @@
+from django import forms
+
+__all__ = ('DeviceSyncForm',)
+
+
+def field_name(selection_key):
+    """
+    Return the form field name of a selection key ("interface.type" -> "interface__type").
+    """
+    return selection_key.replace('.', '__')
+
+
+class DeviceSyncForm(forms.Form):
+    """
+    One unchecked checkbox for every property that differs between a device and
+    its device type.
+    """
+
+    def __init__(self, *args, plan, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.selection_keys = plan.selection_keys
+        for key in self.selection_keys:
+            # NetBox renders BooleanField checkboxes with the form-check-input class
+            self.fields[field_name(key)] = forms.BooleanField(
+                required=False, initial=False
+            )
+
+    def __getitem__(self, name):
+        # Accept selection keys as well as field names
+        return super().__getitem__(field_name(name))
+
+    def selected_keys(self):
+        return [
+            key for key in self.selection_keys if self.cleaned_data.get(field_name(key))
+        ]

netbox_device_type_sync/templates/netbox_device_type_sync/device_sync.html

@@ -0,0 +1,239 @@
+{% extends 'generic/_base.html' %}
+{% load helpers %}
+{% load i18n %}
+
+{% comment %}
+Context:
+  - object:       The device
+  - plan:         diff.SyncPlan
+  - form:         forms.DeviceSyncForm
+  - errors:       Error messages from a failed apply
+  - device_rows:  (DeviceFieldDiff, bound checkbox) pairs
+  - kinds:        {'diff': KindDiff, 'summaries': [(PropertySummary, bound checkbox)]} for changed component types
+  - return_url:   The device page
+{% endcomment %}
+
+{% block title %}{% trans "Sync with device type" %}{% endblock %}
+
+{% block page-header %}
+  <div class="container-fluid">
+    <div class="d-flex justify-content-between align-items-center mt-2">
+      <ol class="breadcrumb" aria-label="breadcrumbs">
+        <li class="breadcrumb-item"><a href="{% url 'dcim:device_list' %}">{% trans "Devices" %}</a></li>
+        <li class="breadcrumb-item">{{ object|linkify }}</li>
+      </ol>
+    </div>
+  </div>
+  {{ block.super }}
+{% endblock page-header %}
+
+{% block subtitle %}
+  <div class="text-secondary fs-5">
+    <ul class="list-inline">
+      <li class="list-inline-item">
+        <i class="mdi mdi-server" title="{% trans "Device" %}"></i> {{ object|linkify }}
+      </li>
+      <li class="list-inline-item">
+        <i class="mdi mdi-chip" title="{% trans "Device type" %}"></i> {{ plan.device_type|linkify }}
+      </li>
+    </ul>
+  </div>
+{% endblock subtitle %}
+
+{% block content %}
+  {% if errors %}
+    <div class="alert alert-danger mt-3" role="alert">
+      <h4 class="alert-title">{% trans "Nothing was changed. Fix these errors and try again:" %}</h4>
+      <ul class="mb-0">
+        {% for error in errors %}
+          <li>{{ error }}</li>
+        {% endfor %}
+      </ul>
+    </div>
+  {% endif %}
+
+  {% if plan.is_empty %}
+    <div class="row mt-3">
+      <div class="col col-md-8 offset-md-2">
+        <div class="card">
+          <div class="card-body text-center py-5">
+            <i class="mdi mdi-check-circle-outline text-success" style="font-size: 3rem;"></i>
+            <h3 class="mt-2">{% trans "The device is in sync with its device type" %}</h3>
+            <p class="text-secondary mb-4">
+              {% blocktrans trimmed with device_type=plan.device_type %}
+                Every component of {{ device_type }} exists on the device, and their properties match.
+              {% endblocktrans %}
+            </p>
+            <a href="{{ return_url }}" class="btn btn-outline-secondary">{% trans "Back to device" %}</a>
+          </div>
+        </div>
+      </div>
+    </div>
+  {% else %}
+    <form action="" method="post" class="object-edit--with-sticky-actions">
+      {% csrf_token %}
+
+      <div class="row mt-3">
+        <div class="col col-lg-10 offset-lg-1">
+
+          <p class="text-secondary">
+            {% blocktrans trimmed %}
+              A checked property is copied from the device type to every component of that type with the same
+              name. An unchecked property keeps the value of the device. Components that are missing on the
+              device are always created. Cables, IP addresses, VLANs and other settings of the components are
+              not changed.
+            {% endblocktrans %}
+          </p>
+
+          {# Device fields #}
+          {% if device_rows %}
+            <div class="card">
+              <h2 class="card-header">{% trans "Device" %}</h2>
+              <table class="table table-hover">
+                <thead>
+                  <tr>
+                    <th class="w-1"></th>
+                    <th>{% trans "Property" %}</th>
+                    <th>{% trans "Device" %}</th>
+                    <th>{% trans "Device type" %}</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {% for diff, field in device_rows %}
+                    <tr>
+                      <td>{{ field }}</td>
+                      <td><label for="{{ field.id_for_label }}" class="mb-0">{{ diff.label }}</label></td>
+                      <td class="text-secondary">{{ diff.current }}</td>
+                      <td>{{ diff.desired }}</td>
+                    </tr>
+                  {% endfor %}
+                </tbody>
+              </table>
+            </div>
+          {% endif %}
+
+          {# Component types #}
+          {% for kind in kinds %}
+            {% with diff=kind.diff %}
+              <div class="card">
+                <h2 class="card-header">
+                  {{ diff.kind.verbose_name_plural }}
+                  <div class="card-actions">
+                    {% if diff.create %}
+                      <span class="badge text-bg-success">
+                        {% blocktrans trimmed count counter=diff.create|length %}
+                          {{ counter }} to create
+                        {% plural %}
+                          {{ counter }} to create
+                        {% endblocktrans %}
+                      </span>
+                    {% endif %}
+                    {% if diff.update %}
+                      <span class="badge text-bg-warning">
+                        {% blocktrans trimmed count counter=diff.update|length %}
+                          {{ counter }} with differences
+                        {% plural %}
+                          {{ counter }} with differences
+                        {% endblocktrans %}
+                      </span>
+                    {% endif %}
+                  </div>
+                </h2>
+
+                {% if diff.create or diff.conflicts %}
+                  <div class="card-body">
+                    {% if diff.create %}
+                      <details>
+                        <summary>
+                          <i class="mdi mdi-plus-circle text-success"></i>
+                          {% blocktrans trimmed count counter=diff.create|length with kind=diff.kind.verbose_name|lower kinds=diff.kind.verbose_name_plural|lower %}
+                            {{ counter }} {{ kind }} will be created
+                          {% plural %}
+                            {{ counter }} {{ kinds }} will be created
+                          {% endblocktrans %}
+                        </summary>
+                        <div class="mt-2">
+                          {% for item in diff.create %}
+                            <span class="badge text-bg-light me-1 mb-1">{{ item.name }}</span>
+                          {% endfor %}
+                        </div>
+                      </details>
+                    {% endif %}
+                    {% if diff.conflicts %}
+                      <div class="alert alert-warning mt-3 mb-0" role="alert">
+                        <i class="mdi mdi-alert"></i>
+                        {% trans "Not created: the name is used by a component of an installed module:" %}
+                        {% for item in diff.conflicts %}
+                          <strong>{{ item.name }}</strong>{% if not forloop.last %}, {% endif %}
+                        {% endfor %}
+                      </div>
+                    {% endif %}
+                  </div>
+                {% endif %}
+
+                {% if kind.summaries %}
+                  <table class="table table-hover">
+                    <thead>
+                      <tr>
+                        <th class="w-1"></th>
+                        <th>{% trans "Property" %}</th>
+                        <th>{% trans "Differs on" %}</th>
+                      </tr>
+                    </thead>
+                    <tbody>
+                      {% for summary, field in kind.summaries %}
+                        <tr>
+                          <td>{{ field }}</td>
+                          <td class="w-25"><label for="{{ field.id_for_label }}" class="mb-0">{{ summary.label }}</label></td>
+                          <td>
+                            <details>
+                              <summary class="text-secondary">
+                                {% blocktrans trimmed count counter=summary.count with kind=diff.kind.verbose_name|lower kinds=diff.kind.verbose_name_plural|lower %}
+                                  {{ counter }} {{ kind }}
+                                {% plural %}
+                                  {{ counter }} {{ kinds }}
+                                {% endblocktrans %}
+                              </summary>
+                              <table class="table table-sm mt-2 mb-0">
+                                <thead>
+                                  <tr>
+                                    <th>{% trans "Name" %}</th>
+                                    <th>{% trans "Device" %}</th>
+                                    <th>{% trans "Device type" %}</th>
+                                  </tr>
+                                </thead>
+                                <tbody>
+                                  {% for name, change in summary.components %}
+                                    <tr>
+                                      <td>{{ name }}</td>
+                                      <td class="text-secondary">{{ change.current }}</td>
+                                      <td>{{ change.desired }}</td>
+                                    </tr>
+                                  {% endfor %}
+                                </tbody>
+                              </table>
+                            </details>
+                          </td>
+                        </tr>
+                      {% endfor %}
+                    </tbody>
+                  </table>
+                {% endif %}
+              </div>
+            {% endwith %}
+          {% endfor %}
+
+        </div>
+      </div>
+
+      <div class="sticky-actions sticky-actions-footer d-print-none" data-sticky-position="full" data-sticky-when="always">
+        <div class="btn-list">
+          <a href="{{ return_url }}" class="btn btn-outline-secondary">{% trans "Cancel" %}</a>
+          <button type="submit" class="btn btn-primary">
+            <i class="mdi mdi-sync"></i> {% trans "Apply" %}
+          </button>
+        </div>
+      </div>
+    </form>
+  {% endif %}
+{% endblock content %}