netbox-pathways 0.1.0__py3-none-any.whl

netbox_pathways/api/serializers.py

@@ -0,0 +1,520 @@
+from circuits.api.serializers_.circuits import CircuitSerializer
+from dcim.api.serializers_.cables import CableSerializer
+from dcim.api.serializers_.sites import LocationSerializer, SiteSerializer
+from netbox.api.fields import ChoiceField
+from netbox.api.serializers import NetBoxModelSerializer
+from rest_framework import serializers as drf_serializers
+from tenancy.api.serializers_.tenants import TenantSerializer
+
+from ..choices import (
+    AerialTypeChoices,
+    BankFaceChoices,
+    ConduitBankConfigChoices,
+    ConduitMaterialChoices,
+    EncasementTypeChoices,
+    PathwayTypeChoices,
+    PlannedRouteStatusChoices,
+    StructureStatusChoices,
+    StructureTypeChoices,
+)
+from ..models import (
+    AerialSpan,
+    CableSegment,
+    CircuitGeometry,
+    Conduit,
+    ConduitBank,
+    ConduitJunction,
+    DirectBuried,
+    Innerduct,
+    Pathway,
+    PathwayLocation,
+    PlannedRoute,
+    SiteGeometry,
+    Structure,
+)
+
+
+class StructureSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:structure-detail",
+    )
+    status = ChoiceField(choices=StructureStatusChoices, required=False)
+    structure_type = ChoiceField(choices=StructureTypeChoices, required=False, allow_blank=True)
+    site = SiteSerializer(nested=True, required=False, allow_null=True)
+    tenant = TenantSerializer(nested=True, required=False, allow_null=True)
+    no_pathways = drf_serializers.SerializerMethodField(read_only=True)
+    description = drf_serializers.SerializerMethodField(read_only=True)
+
+    class Meta:
+        model = Structure
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "name",
+            "status",
+            "structure_type",
+            "site",
+            "location",
+            "height",
+            "width",
+            "length",
+            "depth",
+            "elevation",
+            "installation_date",
+            "tenant",
+            "access_notes",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+            "no_pathways",
+            "description",
+        ]
+        brief_fields = (
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "label",
+            "structure_type",
+            "no_pathways",
+            "description",
+        )
+
+    def get_no_pathways(self, obj):
+        if hasattr(obj, "_has_pathways"):
+            return not obj._has_pathways
+        return None
+
+    def get_description(self, obj):
+        if hasattr(obj, "_has_pathways") and not obj._has_pathways:
+            return "No connected pathways"
+        return None
+
+
+# --- Shared FK field declarations for pathway subtypes ---
+
+
+def _pathway_fk_fields():
+    """Common FK field declarations for all pathway-based serializers."""
+    return {
+        "start_structure": StructureSerializer(nested=True, required=False, allow_null=True),
+        "end_structure": StructureSerializer(nested=True, required=False, allow_null=True),
+        "start_location": LocationSerializer(nested=True, required=False, allow_null=True),
+        "end_location": LocationSerializer(nested=True, required=False, allow_null=True),
+        "tenant": TenantSerializer(nested=True, required=False, allow_null=True),
+    }
+
+
+class ConduitBankSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:conduitbank-detail",
+    )
+    start_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    end_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    start_face = ChoiceField(choices=BankFaceChoices, required=False, allow_blank=True)
+    end_face = ChoiceField(choices=BankFaceChoices, required=False, allow_blank=True)
+    configuration = ChoiceField(choices=ConduitBankConfigChoices, required=False, allow_blank=True)
+    encasement_type = ChoiceField(choices=EncasementTypeChoices, required=False, allow_blank=True)
+    tenant = TenantSerializer(nested=True, required=False, allow_null=True)
+
+    class Meta:
+        model = ConduitBank
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "label",
+            "start_structure",
+            "end_structure",
+            "start_face",
+            "end_face",
+            "tenant",
+            "path",
+            "length",
+            "configuration",
+            "total_conduits",
+            "encasement_type",
+            "installation_date",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "label")
+
+
+class PathwaySerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:pathway-detail",
+    )
+    pathway_type = ChoiceField(choices=PathwayTypeChoices, required=False, allow_blank=True)
+    start_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    end_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    start_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    end_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    tenant = TenantSerializer(nested=True, required=False, allow_null=True)
+    cables_routed = drf_serializers.IntegerField(read_only=True)
+
+    class Meta:
+        model = Pathway
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "label",
+            "pathway_type",
+            "path",
+            "start_structure",
+            "end_structure",
+            "start_location",
+            "end_location",
+            "tenant",
+            "length",
+            "cables_routed",
+            "installation_date",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "label", "pathway_type")
+
+
+class ConduitSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:conduit-detail",
+    )
+    material = ChoiceField(choices=ConduitMaterialChoices, required=False, allow_blank=True)
+    start_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    end_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    start_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    end_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    conduit_bank = ConduitBankSerializer(nested=True, required=False, allow_null=True)
+    tenant = TenantSerializer(nested=True, required=False, allow_null=True)
+    cables_routed = drf_serializers.IntegerField(read_only=True)
+
+    class Meta:
+        model = Conduit
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "label",
+            "pathway_type",
+            "path",
+            "start_structure",
+            "end_structure",
+            "start_location",
+            "end_location",
+            "material",
+            "inner_diameter",
+            "outer_diameter",
+            "depth",
+            "conduit_bank",
+            "bank_position",
+            "start_junction",
+            "end_junction",
+            "length",
+            "cables_routed",
+            "installation_date",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "label", "material")
+
+
+class AerialSpanSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:aerialspan-detail",
+    )
+    aerial_type = ChoiceField(choices=AerialTypeChoices, required=False, allow_blank=True)
+    start_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    end_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    start_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    end_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    tenant = TenantSerializer(nested=True, required=False, allow_null=True)
+    cables_routed = drf_serializers.IntegerField(read_only=True)
+
+    class Meta:
+        model = AerialSpan
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "label",
+            "pathway_type",
+            "path",
+            "start_structure",
+            "end_structure",
+            "start_location",
+            "end_location",
+            "aerial_type",
+            "attachment_height",
+            "sag",
+            "messenger_size",
+            "wind_loading",
+            "ice_loading",
+            "length",
+            "cables_routed",
+            "installation_date",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "label", "aerial_type")
+
+
+class DirectBuriedSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:directburied-detail",
+    )
+    start_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    end_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    start_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    end_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    tenant = TenantSerializer(nested=True, required=False, allow_null=True)
+    cables_routed = drf_serializers.IntegerField(read_only=True)
+
+    class Meta:
+        model = DirectBuried
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "label",
+            "pathway_type",
+            "path",
+            "start_structure",
+            "end_structure",
+            "start_location",
+            "end_location",
+            "burial_depth",
+            "warning_tape",
+            "tracer_wire",
+            "armor_type",
+            "length",
+            "cables_routed",
+            "installation_date",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "label")
+
+
+class InnerductSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:innerduct-detail",
+    )
+    start_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    end_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    start_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    end_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    parent_conduit = ConduitSerializer(nested=True, required=False, allow_null=True)
+    cables_routed = drf_serializers.IntegerField(read_only=True)
+
+    class Meta:
+        model = Innerduct
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "label",
+            "pathway_type",
+            "path",
+            "start_structure",
+            "end_structure",
+            "start_location",
+            "end_location",
+            "parent_conduit",
+            "size",
+            "color",
+            "position",
+            "length",
+            "cables_routed",
+            "installation_date",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "label", "size")
+
+
+class ConduitJunctionSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:conduitjunction-detail",
+    )
+    trunk_conduit = ConduitSerializer(nested=True, required=False, allow_null=True)
+    branch_conduit = ConduitSerializer(nested=True, required=False, allow_null=True)
+    towards_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+
+    class Meta:
+        model = ConduitJunction
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "label",
+            "trunk_conduit",
+            "branch_conduit",
+            "towards_structure",
+            "position_on_trunk",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "label")
+
+
+class PathwayLocationSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:pathwaylocation-detail",
+    )
+    pathway = PathwaySerializer(nested=True, required=False, allow_null=True)
+    site = SiteSerializer(nested=True, required=False, allow_null=True)
+    location = LocationSerializer(nested=True, required=False, allow_null=True)
+
+    class Meta:
+        model = PathwayLocation
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "pathway",
+            "site",
+            "location",
+            "sequence",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "pathway", "sequence")
+
+
+class CableSegmentSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:cablesegment-detail",
+    )
+    cable = CableSerializer(nested=True, required=False, allow_null=True)
+    pathway = PathwaySerializer(nested=True, required=False, allow_null=True)
+
+    class Meta:
+        model = CableSegment
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "cable",
+            "pathway",
+            "sequence",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "cable", "pathway", "sequence")
+
+
+class SiteGeometrySerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:sitegeometry-detail",
+    )
+    site = SiteSerializer(nested=True, required=False, allow_null=True)
+    structure = StructureSerializer(nested=True, required=False, allow_null=True)
+
+    class Meta:
+        model = SiteGeometry
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "site",
+            "structure",
+            "geometry",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "site")
+
+
+class CircuitGeometrySerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:circuitgeometry-detail",
+    )
+    circuit = CircuitSerializer(nested=True, required=False, allow_null=True)
+
+    class Meta:
+        model = CircuitGeometry
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "circuit",
+            "path",
+            "provider_reference",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "circuit")
+
+
+class PlannedRouteSerializer(NetBoxModelSerializer):
+    url = drf_serializers.HyperlinkedIdentityField(
+        view_name="plugins-api:netbox_pathways-api:plannedroute-detail",
+    )
+    status = ChoiceField(choices=PlannedRouteStatusChoices, required=False)
+    start_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    end_structure = StructureSerializer(nested=True, required=False, allow_null=True)
+    start_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    end_location = LocationSerializer(nested=True, required=False, allow_null=True)
+    tenant = TenantSerializer(nested=True, required=False, allow_null=True)
+    cable = CableSerializer(nested=True, required=False, allow_null=True)
+
+    class Meta:
+        model = PlannedRoute
+        fields = [
+            "id",
+            "url",
+            "display_url",
+            "display",
+            "name",
+            "status",
+            "start_structure",
+            "end_structure",
+            "start_location",
+            "end_location",
+            "pathway_ids",
+            "constraints",
+            "tenant",
+            "cable",
+            "comments",
+            "tags",
+            "created",
+            "last_updated",
+        ]
+        brief_fields = ("id", "url", "display_url", "display", "name", "status")

netbox_pathways/api/traversal.py

@@ -0,0 +1,48 @@
+"""
+REST API endpoints for graph traversal operations.
+"""
+
+from rest_framework import status
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from ..graph import trace_cable
+
+
+class CableTraceView(APIView):
+    """
+    Trace a cable's physical route through pathways.
+
+    GET /api/plugins/netbox-pathways/traversal/cable-trace/?cable_id=<id>
+    """
+
+    permission_classes = [IsAuthenticated]
+
+    def get(self, request):
+        cable_id = request.query_params.get("cable_id")
+        if not cable_id:
+            return Response(
+                {"error": "cable_id is required"},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        try:
+            cable_id = int(cable_id)
+        except (TypeError, ValueError):
+            return Response(
+                {"error": "cable_id must be an integer"},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        segments = trace_cable(cable_id)
+        total_length = sum(s["length"] or 0 for s in segments)
+
+        return Response(
+            {
+                "cable_id": cable_id,
+                "segment_count": len(segments),
+                "total_length": total_length,
+                "segments": segments,
+            }
+        )

netbox_pathways/api/urls.py

@@ -0,0 +1,46 @@
+from django.urls import path
+from netbox.api.routers import NetBoxRouter
+
+from . import views
+from .external_geo import ExternalLayerGeoView
+from .geo import (
+    AerialSpanGeoViewSet,
+    CircuitGeoViewSet,
+    ConduitBankGeoViewSet,
+    ConduitGeoViewSet,
+    DirectBuriedGeoViewSet,
+    PathwayGeoViewSet,
+    StructureGeoViewSet,
+)
+from .traversal import CableTraceView
+
+router = NetBoxRouter()
+router.register("structures", views.StructureViewSet)
+router.register("conduit-banks", views.ConduitBankViewSet)
+router.register("pathways", views.PathwayViewSet)
+router.register("conduits", views.ConduitViewSet)
+router.register("aerial-spans", views.AerialSpanViewSet)
+router.register("direct-buried", views.DirectBuriedViewSet)
+router.register("innerducts", views.InnerductViewSet)
+router.register("junctions", views.ConduitJunctionViewSet)
+router.register("pathway-locations", views.PathwayLocationViewSet)
+router.register("cable-segments", views.CableSegmentViewSet)
+router.register("site-geometries", views.SiteGeometryViewSet)
+router.register("circuit-geometries", views.CircuitGeometryViewSet)
+router.register("planned-routes", views.PlannedRouteViewSet)
+
+# GeoJSON endpoints for QGIS / GIS client consumption
+router.register("geo/structures", StructureGeoViewSet, basename="geo-structure")
+router.register("geo/pathways", PathwayGeoViewSet, basename="geo-pathway")
+router.register("geo/conduit-banks", ConduitBankGeoViewSet, basename="geo-conduitbank")
+router.register("geo/conduits", ConduitGeoViewSet, basename="geo-conduit")
+router.register("geo/aerial-spans", AerialSpanGeoViewSet, basename="geo-aerialspan")
+router.register("geo/direct-buried", DirectBuriedGeoViewSet, basename="geo-directburied")
+router.register("geo/circuits", CircuitGeoViewSet, basename="geo-circuit")
+
+urlpatterns = router.urls + [
+    # External plugin map layer endpoint
+    path("geo/external/<str:layer_name>/", ExternalLayerGeoView.as_view(), name="external-geo"),
+    # Graph traversal endpoints
+    path("traversal/cable-trace/", CableTraceView.as_view(), name="traversal-cable-trace"),
+]