netbox-data-import 2.0.0__tar.gz → 2.1.0__tar.gz

{netbox_data_import-2.0.0 → netbox_data_import-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netbox-data-import
-Version: 2.0.0
+Version: 2.1.0
 Summary: NetBox plugin for importing data from external DCIM systems
 Author: Marcin Zieba
 License-Expression: Apache-2.0
@@ -18,6 +18,7 @@ Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: google-re2>=1.1.20251105
 Requires-Dist: openpyxl>=3.1
 Requires-Dist: pyyaml>=6
+Requires-Dist: requests>=2.33.0
 Dynamic: license-file
 
 <!--

netbox_data_import-2.1.0/netbox_data_import/__init__.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2025 Marcin Zieba <marcinpsk@gmail.com>
+from typing import Any
+
+from netbox.plugins import PluginConfig
+
+__version__ = "2.1.0"
+
+
+class NetBoxDataImportConfig(PluginConfig):
+    """NetBox plugin configuration for the Data Import plugin."""
+
+    name = "netbox_data_import"
+    verbose_name = "NetBox Data Import"
+    description = "NetBox plugin for importing data from external DCIM systems"
+    version = __version__
+    base_url = "data-import"
+    author = "Marcin Zieba"
+    author_email = "marcinpsk@gmail.com"
+    min_version = "4.6.0"
+    graphql_schema = "graphql.schema.schema"
+
+    default_settings: dict[str, Any] = {
+        # A deployment that names no allowlist reaches no origin, rather than every origin.
+        "inference_backend_origin_allowlist": [],
+    }
+
+    @classmethod
+    def validate(cls, user_config, netbox_version):
+        """Reject a malformed Inference Backend configuration before the application serves a request."""
+        super().validate(user_config, netbox_version)
+
+        from django.core.exceptions import ImproperlyConfigured
+
+        from .inference_settings import InvalidInferenceConfiguration, validate_plugin_settings
+
+        try:
+            validate_plugin_settings(user_config)
+        except InvalidInferenceConfiguration as exc:
+            raise ImproperlyConfigured(f"Plugin {cls.__module__} has an invalid configuration: {exc}") from exc
+
+    def ready(self):
+        """Import the jobs module, which NetBox does not load, so its @system_job registration runs."""
+        super().ready()
+
+        from . import jobs
+
+
+config = NetBoxDataImportConfig

{netbox_data_import-2.0.0 → netbox_data_import-2.1.0}/netbox_data_import/api/serializers.py

@@ -25,6 +25,12 @@ from ..models import (
 )
 
 
+def _validate_candidate_values(candidate_values):
+    """Require a JSON object at the Contact candidate boundary."""
+    if not isinstance(candidate_values, dict):
+        raise TypeError("Contact candidate values must be a JSON object.")
+
+
 class PolicySectionApplicabilityMixin:
     """Apply the shared policy-section applicability rule on the REST write path."""
 
@@ -222,8 +228,7 @@ class SourceResolutionSerializer(PolicySectionSerializer):
             resolved_fields = attrs.get("resolved_fields", getattr(instance, "resolved_fields", None))
             try:
                 candidate_values = json.loads(original_value)
-                if not isinstance(candidate_values, dict):
-                    raise ValueError
+                _validate_candidate_values(candidate_values)
                 configured_sources = profile.column_mappings.filter(target_field="candidate:contact").values_list(
                     "source_column", flat=True
                 )

{netbox_data_import-2.0.0 → netbox_data_import-2.1.0}/netbox_data_import/cable_target.py

@@ -41,6 +41,23 @@ from .values import identity_text, source_text
 CABLE_STATUS = "connected"
 ELIGIBLE_TERMINATION_LIMIT = 20
 
+# Section 10.2 badge vocabulary. T8 adds the proposal states to the same set.
+UNRESOLVED = "unresolved"
+AUTOMATICALLY_RESOLVED = "automatically resolved"
+MANUALLY_RESOLVED = "manually resolved"
+
+CREATE_SEGMENT = "create"
+REUSE_SEGMENT = "reuse existing"
+CONFLICT_SEGMENT = "conflict"
+_CONFLICT_CODES = frozenset(
+    {
+        "cable.termination_occupied",
+        "cable.multi_termination_conflict",
+        "cable.planned_termination_conflict",
+        "cable.resolved_segment_conflict",
+    }
+)
+
 _KIND_BY_MODEL_NAME = {
     "interface": INTERFACE_KIND,
     "frontport": FRONT_PORT_KIND,
@@ -190,7 +207,10 @@ class _TraceAnalysis:
     segments: list = field(default_factory=list)
     proven: dict = field(default_factory=dict)
     policies: dict = field(default_factory=dict)
+    terminations: dict = field(default_factory=dict)
+    topology_read: bool = False
     logical_cable: Any = None
+    retains_logical_cable: bool = False
     blocked: bool = False
     invalid: bool = False
 
@@ -204,10 +224,16 @@ class _TraceAnalysis:
         """Return the desired segments no existing Cable already proves."""
         return [segment for segment in self.segments if segment.index not in self.proven]
 
+    @property
+    def deleted_logical_cable(self):
+        """Return the Logical Cable this trace removes, which a Cable that proves its path is not."""
+        return None if self.retains_logical_cable else self.logical_cable
+
     @property
     def delete_identity(self) -> str | None:
         """Return the Planned Change identity that removes this trace's Logical Cable."""
-        return None if self.logical_cable is None else _delete_identity(self.logical_cable.cable.pk)
+        removed = self.deleted_logical_cable
+        return None if removed is None else _delete_identity(removed.cable.pk)
 
     def error(self, code: str, display: dict, identities=()) -> None:
         """Record one blocking or invalidating finding."""
@@ -502,19 +528,64 @@ class _CableBatch:
         devices = self._devices.get(identity_text(reference.device), [])
         if len(devices) != 1:
             analysis.block("trace.device_unresolved", {**_reference_display(reference), "matches": len(devices)})
+            # With no resolved Device there is nothing to pick from, so the picker cannot help here.
+            self._record_resolution(
+                analysis,
+                reference,
+                UNRESOLVED,
+                None,
+                reason=f"The source names {len(devices)} matching Devices, so no port list applies.",
+            )
             return None
         device = devices[0]
         stored = self._stored.get(_field_key(reference))
         if stored is not None:
-            return self._stored_termination(analysis, reference, device, stored)
+            termination = self._stored_termination(analysis, reference, device, stored)
+            state = UNRESOLVED if termination is None else MANUALLY_RESOLVED
+            self._record_resolution(analysis, reference, state, termination)
+            return termination
         kind = claimed_termination_kind(reference.port_class)
         candidates = self._components_for(device.pk, kind).get(identity_text(reference.port), [])
         if len(candidates) != 1:
             analysis.block(
                 "cable.termination_unresolved", {**_reference_display(reference), "matches": len(candidates)}
             )
+            self._record_resolution(analysis, reference, UNRESOLVED, None)
             return None
-        return self._termination(candidates[0])
+        termination = self._termination(candidates[0])
+        self._record_resolution(analysis, reference, AUTOMATICALLY_RESOLVED, termination)
+        return termination
+
+    @staticmethod
+    def _record_resolution(
+        analysis: _TraceAnalysis,
+        reference,
+        state: str,
+        termination,
+        reason: str = "",
+        role: str = TERMINATION_ROLE,
+    ) -> None:
+        """Record how one Termination Reference was settled, for its badge and its picker."""
+        key = _field_key(reference, role)
+        claimed = claimed_termination_kind(reference.port_class)
+        if role == MAPPED_PEER_ROLE:
+            # The picker offers the ports on the far side of the panel, which are the opposite kind.
+            kind = REAR_PORT_KIND if claimed == FRONT_PORT_KIND else FRONT_PORT_KIND
+            label = f"{_endpoint_label(reference)} (mapped peer)"
+        else:
+            kind, label = claimed, _endpoint_label(reference)
+        analysis.terminations.setdefault(
+            key,
+            {
+                "field_key": key,
+                "label": label,
+                "kind": kind,
+                "state": state,
+                "selected": "" if termination is None else termination.display,
+                "selectable": not reason,
+                "reason": reason,
+            },
+        )
 
     def _stored_termination(self, analysis: _TraceAnalysis, reference, device, stored) -> _Termination | None:
         """Return the object one saved decision selected, rechecked against current target state."""
@@ -714,7 +785,9 @@ class _CableBatch:
             )
             if selected in peers:
                 peer, mapping = peers[selected]
+                self._record_resolution(analysis, reference, MANUALLY_RESOLVED, peer, role=MAPPED_PEER_ROLE)
                 return self._substituted(analysis, reference, exit_end, peer, mapping)
+        self._record_resolution(analysis, reference, UNRESOLVED, None, role=MAPPED_PEER_ROLE)
         analysis.block(
             "cable.ambiguous_mapped_peer",
             {
@@ -835,6 +908,8 @@ class _CableBatch:
         """
         pending = self._writing()
         for analysis in pending:
+            # Only these analyses look at the live topology, so only they may report what is there.
+            analysis.topology_read = True
             for segment in analysis.segments:
                 candidate = self._occupied.get(segment.left.key)
                 proven = candidate if candidate is not None and candidate.satisfies(segment) else None
@@ -873,7 +948,7 @@ class _CableBatch:
             {"segment_index": 0, **cable_display},
             identities=cable_identities,
         )
-        analysis.logical_cable = None
+        analysis.retains_logical_cable = True
 
     def _note_reuse(self, analysis: _TraceAnalysis, segment: _DesiredSegment, proven: _ExistingCable) -> None:
         """Record the proven physical segment, so its live state joins the unit fingerprint."""
@@ -908,7 +983,8 @@ class _CableBatch:
 
     def _report_conflicts(self, analysis: _TraceAnalysis) -> None:
         """Block the trace when a Cable this import may not touch holds a termination it needs."""
-        logical_id = None if analysis.logical_cable is None else analysis.logical_cable.cable.pk
+        removed = analysis.deleted_logical_cable
+        logical_id = None if removed is None else removed.cable.pk
         for segment in analysis.pending:
             for termination in segment.terminations:
                 occupying = self._occupied.get(termination.key)
@@ -965,7 +1041,7 @@ class _CableBatch:
         if analysis.pending and not self.actor.has_perm("dcim.add_cable"):
             analysis.block("cable.permission_denied", {"permission": "dcim.add_cable"})
             return
-        logical = analysis.logical_cable
+        logical = analysis.deleted_logical_cable
         if logical is not None and not self.actor.has_perm("dcim.delete_cable", logical.cable):
             cable_display, cable_identities = self._cable_diagnostic_disclosure(logical.cable)
             analysis.block(
@@ -1076,16 +1152,99 @@ class _CableBatch:
             disposition=disposition,
             changes=changes,
             diagnostics=tuple(analysis.diagnostics),
-            display={**analysis.display, "detail": self._detail(analysis, disposition)},
+            display={
+                **analysis.display,
+                "detail": self._detail(analysis, disposition),
+                "trace": self._workspace(analysis, bool(changes)),
+            },
         )
 
+    def _workspace(self, analysis: _TraceAnalysis, writes: bool) -> dict:
+        """Return what the three review workspace panels show for one Source Trace."""
+        summary = analysis.trace.endpoint_summary
+        resolved = {segment.index: segment for segment in analysis.segments}
+        by_reference = self._resolved.get(analysis.identity, {})
+        conflicted = {
+            diagnostic.display.get("segment_index")
+            for diagnostic in analysis.diagnostics
+            if diagnostic.code in _CONFLICT_CODES
+        }
+        segments = []
+        stated_segments = list(analysis.trace.segments)
+        for index, stated in enumerate(stated_segments):
+            planned = resolved.get(index)
+            source_left, source_right = _endpoint_label(stated.left), _endpoint_label(stated.right)
+            left = source_left if planned is None else planned.left.display
+            right = source_right if planned is None else planned.right.display
+            segments.append(
+                {
+                    "index": index,
+                    "cable_class": source_text(stated.cable_class),
+                    "source_left": source_left,
+                    "source_right": source_right,
+                    "left": left,
+                    "right": right,
+                    # A path that re-enters one panel implies a claim the source never states.
+                    "pass_through": index > 0 and same_device_and_cards(stated_segments[index - 1].right, stated.left),
+                    # Planning substituted the entry port only where the source re-used one port.
+                    "substituted": self._entered_through_claim(planned, by_reference.get(stated.left.identity_key)),
+                    "status": self._segment_status(analysis, index, conflicted, planned, writes),
+                }
+            )
+        return {
+            "identity": analysis.trace.identity,
+            "endpoints": {
+                "from": _endpoint_label(summary.from_termination),
+                "to": _endpoint_label(summary.to_termination),
+            },
+            "segments": segments,
+            "logical_cable": self._logical_cable_display(analysis),
+            "topology_known": analysis.topology_read,
+            # A unit with no changes proposes nothing, so the panel must not offer to delete one.
+            "deletes_logical_cable": writes and analysis.deleted_logical_cable is not None,
+            "terminations": list(analysis.terminations.values()),
+        }
+
+    @staticmethod
+    def _entered_through_claim(planned: _DesiredSegment | None, stated: _Termination | None) -> bool:
+        """Return whether planning entered this segment through a port the source never stated."""
+        return planned is not None and stated is not None and planned.left.key != stated.key
+
+    @staticmethod
+    def _segment_status(analysis: _TraceAnalysis, index: int, conflicted: set, planned, writes: bool) -> str:
+        """Return the verdict the proposed panel shows for one segment, or none for an unplanned one."""
+        if index in conflicted:
+            return CONFLICT_SEGMENT
+        if planned is None:
+            return ""
+        if index in analysis.proven:
+            return REUSE_SEGMENT
+        # A blocked unit contributes no change, so nothing here is going to be created.
+        return CREATE_SEGMENT if writes else ""
+
+    def _logical_cable_display(self, analysis: _TraceAnalysis) -> dict | None:
+        """Return the Logical Cable NetBox holds for this trace, as far as the actor may see it."""
+        if analysis.logical_cable is None:
+            return None
+        cable = analysis.logical_cable.cable
+        disclosure, _identities = self._cable_diagnostic_disclosure(cable)
+        if not disclosure["cable_visible"]:
+            return {"visible": False, "display": "", "description": "", "tags": []}
+        # Section 6.3 reviews what the deletion removes, which the deletion payload also carries.
+        return {
+            "visible": True,
+            "display": disclosure["cable"],
+            "description": cable.description,
+            "tags": sorted(cable.tags.values_list("name", flat=True)),
+        }
+
     def _changes(self, analysis: _TraceAnalysis) -> tuple[PlannedChange, ...]:
         """Return the deletion and the creations one actionable trace performs, in that order."""
         if analysis.stopped:
             return ()
         changes = []
-        if analysis.logical_cable is not None:
-            changes.append(self._delete_change(analysis.logical_cable))
+        if analysis.deleted_logical_cable is not None:
+            changes.append(self._delete_change(analysis.deleted_logical_cable))
         changes.extend(self._create_change(segment, analysis.policies[segment.index]) for segment in analysis.pending)
         return tuple(changes)
 
@@ -1130,7 +1289,7 @@ class _CableBatch:
         if disposition != Disposition.ACTIONABLE:
             return ""
         count = len(analysis.pending)
-        if analysis.logical_cable is not None:
+        if analysis.deleted_logical_cable is not None:
             return f"Would replace the logical cable with {count} physical segment(s)."
         return f"Would create {count} physical segment(s)."
 
@@ -1269,8 +1428,14 @@ def _cable_terminations(cable_id: int) -> list:
 
 
 __all__ = (
+    "AUTOMATICALLY_RESOLVED",
     "CABLE_STATUS",
+    "CONFLICT_SEGMENT",
+    "CREATE_SEGMENT",
     "ELIGIBLE_TERMINATION_LIMIT",
+    "MANUALLY_RESOLVED",
+    "REUSE_SEGMENT",
+    "UNRESOLVED",
     "CableModule",
     "EligibleTerminations",
     "eligible_terminations",

{netbox_data_import-2.0.0 → netbox_data_import-2.1.0}/netbox_data_import/field_keys.py

@@ -70,14 +70,19 @@ def termination_field_key(*, device, cards, port, kind: str, role: str = TERMINA
     )
 
 
+def _validate_termination_field_data(data):
+    """Reject malformed termination field-key data before canonicalization."""
+    if not isinstance(data, dict) or set(data) != {"cards", "device", "kind", "port", "role"}:
+        raise ValueError
+    if not all(isinstance(data[name], str) for name in data):
+        raise ValueError
+
+
 def parse_termination_field_key(value: str) -> dict[str, str]:
     """Parse an exact canonical termination field key."""
     try:
         data = json.loads(value)
-        if not isinstance(data, dict) or set(data) != {"cards", "device", "kind", "port", "role"}:
-            raise ValueError
-        if not all(isinstance(data[name], str) for name in data):
-            raise ValueError
+        _validate_termination_field_data(data)
         canonical = termination_field_key(**data)
     except (TypeError, ValueError) as exc:
         raise ValueError(f"'{value}' is not a canonical termination field key.") from exc

{netbox_data_import-2.0.0 → netbox_data_import-2.1.0}/netbox_data_import/forms.py

@@ -12,6 +12,7 @@ from .catalog import CATALOG
 from .models import (
     CableClassMapping,
     ImportProfile,
+    InferenceBackend,
     ColumnMapping,
     ClassRoleMapping,
     DeviceTypeMapping,
@@ -285,6 +286,32 @@ class ColumnTransformRuleForm(forms.ModelForm):
             self.fields[name].choices = [("", "---------"), *preserved]
 
 
+class InferenceBackendForm(NetBoxModelForm):
+    """Create or edit one AI backend. Model validation applies the api_root trust boundary."""
+
+    class Meta:
+        model = InferenceBackend
+        fields = (
+            "backend_key",
+            "display_name",
+            "adapter_type",
+            "api_root",
+            "model",
+            "authentication",
+            "response_mode",
+            "credential_reference",
+            "connect_timeout",
+            "read_timeout",
+            "enabled",
+            "tags",
+        )
+        help_texts = {
+            "credential_reference": (
+                "A typed Vault KV v2 reference: backend, mount, path and field. It never holds a key value."
+            ),
+        }
+
+
 class ImportSetupForm(forms.Form):
     """Form for the import wizard step 1: select profile, upload file, choose site/location/tenant."""
 

{netbox_data_import-2.0.0 → netbox_data_import-2.1.0}/netbox_data_import/import_engine.py

@@ -9,6 +9,7 @@ workbook, no column and no NetBox object type.
 
 from __future__ import annotations
 
+from contextlib import suppress
 from typing import cast
 
 from django.core.exceptions import ValidationError
@@ -201,7 +202,7 @@ class ImportEngine:
                 rolled_back=failure.rolled_back,
                 not_attempted=failure.not_attempted,
             )
-            raise failure.cause
+            raise failure.cause from failure
         except Exception as exc:
             # Every other failure after the reservation, so the row can never stay pending.
             cls._mark_failed(
@@ -335,10 +336,8 @@ class ImportEngine:
     @staticmethod
     def _mark_failed(execution, **detail) -> None:
         """Finish a failed row unless a concurrent finisher already chose its outcome."""
-        try:
+        with suppress(ValueError):
             execution.mark_failed(**detail)
-        except ValueError:
-            pass
 
     @staticmethod
     def _stored_source(profile, source_document) -> SourceDocument: