Merge pull request #741 from netbox-community/434-port-trace

434 Add /path to front and rear ports and Virtual Circuits

Author: bctiemann

docs/api.md

@@ -0,0 +1,75 @@
+# API Core Classes
+
+This page documents the core classes that form pyNetBox's API structure.
+
+## Overview
+
+PyNetBox uses a layered architecture to interact with NetBox:
+
+1. **Api** - The main entry point that creates connections to NetBox
+2. **App** - Represents NetBox applications (dcim, ipam, circuits, etc.)
+3. **Endpoint** - Provides CRUD operations for specific API endpoints
+
+```python
+import pynetbox
+
+# Create API connection (Api class)
+nb = pynetbox.api('http://localhost:8000', token='your-token')
+
+# Access an app (App class)
+nb.dcim  # Returns an App instance
+
+# Access an endpoint (Endpoint class)
+nb.dcim.devices  # Returns an Endpoint instance
+
+# Use endpoint methods
+devices = nb.dcim.devices.all()
+```
+
+## Api Class
+
+The `Api` class is the main entry point for interacting with NetBox. It manages the HTTP session, authentication, and provides access to NetBox applications.
+
+::: pynetbox.core.api.Api
+    handler: python
+    options:
+        members:
+            - __init__
+            - create_token
+            - openapi
+            - status
+            - version
+            - activate_branch
+        show_source: true
+        show_root_heading: true
+        heading_level: 3
+
+## App Class
+
+The `App` class represents a NetBox application (such as dcim, ipam, circuits). When you access an attribute on the `Api` object, it returns an `App` instance. Accessing attributes on an `App` returns `Endpoint` objects.
+
+::: pynetbox.core.app.App
+    handler: python
+    options:
+        members:
+            - config
+        show_source: true
+        show_root_heading: true
+        heading_level: 3
+
+## Relationship to Endpoints
+
+When you access an attribute on an `App` object, it returns an [Endpoint](endpoint.md) instance:
+
+```python
+# nb.dcim is an App instance
+# nb.dcim.devices is an Endpoint instance
+devices_endpoint = nb.dcim.devices
+
+# Endpoint provides CRUD methods
+all_devices = devices_endpoint.all()
+device = devices_endpoint.get(1)
+new_device = devices_endpoint.create(name='test', site=1, device_type=1, device_role=1)
+```
+
+See the [Endpoint documentation](endpoint.md) for details on available methods.

docs/circuits.md

@@ -0,0 +1,112 @@
+# Circuits
+
+This page documents special methods available for Circuits models in pyNetBox.
+
+!!! note "Standard API Operations"
+    Standard CRUD operations (`.all()`, `.filter()`, `.get()`, `.create()`, `.update()`, `.delete()`) follow NetBox's REST API patterns. Refer to the [NetBox API documentation](https://demo.netbox.dev/api/docs/) for details on available endpoints and filters.
+
+## Circuit Terminations
+
+### Cable Path Tracing
+
+Circuit terminations support cable path tracing through the `paths()` method. This method returns all cable paths that traverse through the circuit termination, showing the complete connectivity from origin to destination.
+
+**Example:**
+```python
+# Get a circuit termination
+circuit_term = nb.circuits.circuit_terminations.get(circuit_id=123, term_side='A')
+
+# Get all cable paths through this termination
+paths = circuit_term.paths()
+
+# Each path contains origin, destination, and path segments
+for path_info in paths:
+    print(f"Origin: {path_info['origin']}")
+    print(f"Destination: {path_info['destination']}")
+    print("Path segments:")
+    for segment in path_info['path']:
+        for obj in segment:
+            print(f"  - {obj}")
+
+# Example: Find what a circuit connects to
+circuit = nb.circuits.circuits.get(cid='CIRCUIT-001')
+terminations = nb.circuits.circuit_terminations.filter(circuit_id=circuit.id)
+
+for term in terminations:
+    print(f"\nTermination {term.term_side}:")
+    paths = term.paths()
+    if paths:
+        for path in paths:
+            if path['destination']:
+                print(f"  Connected to: {path['destination']}")
+            else:
+                print("  No destination (incomplete path)")
+    else:
+        print("  No cable paths")
+```
+
+**Path Structure:**
+
+The `paths()` method returns a list of dictionaries, where each dictionary represents a complete cable path:
+
+- `origin`: The starting endpoint of the path (Record object or None if unconnected)
+- `destination`: The ending endpoint of the path (Record object or None if unconnected)
+- `path`: A list of path segments, where each segment is a list of Record objects representing the components in that segment (cables, terminations, interfaces, etc.)
+
+## Virtual Circuits
+
+### Overview
+
+Virtual circuits also support cable path tracing through the `paths()` method.
+
+**Example:**
+```python
+# Get a virtual circuit
+vcircuit = nb.circuits.virtual_circuits.get(cid='VPLS-001')
+print(f"Virtual Circuit: {vcircuit.cid}")
+print(f"Provider Network: {vcircuit.provider_network.name}")
+print(f"Type: {vcircuit.type.name}")
+
+# List all terminations for a virtual circuit
+terminations = nb.circuits.virtual_circuit_terminations.filter(
+    virtual_circuit_id=vcircuit.id
+)
+for term in terminations:
+    print(f"Termination Role: {term.role}")
+```
+
+### Virtual Circuit Termination Path Tracing
+
+Virtual circuit terminations also support cable path tracing through the `paths()` method.
+
+**Example:**
+```python
+# Get a virtual circuit termination
+vterm = nb.circuits.virtual_circuit_terminations.get(
+    virtual_circuit_id=123, role='hub'
+)
+
+# Get all cable paths through this termination
+paths = vterm.paths()
+
+# Analyze the connectivity
+for path_info in paths:
+    print(f"Origin: {path_info['origin']}")
+    print(f"Destination: {path_info['destination']}")
+    print("Path segments:")
+    for segment in path_info['path']:
+        for obj in segment:
+            print(f"  - {obj}")
+
+# Example: Find all devices connected via a virtual circuit
+vcircuit = nb.circuits.virtual_circuits.get(cid='VPLS-001')
+terminations = nb.circuits.virtual_circuit_terminations.filter(
+    virtual_circuit_id=vcircuit.id
+)
+
+print(f"Virtual Circuit {vcircuit.cid} connectivity:")
+for term in terminations:
+    paths = term.paths()
+    if paths and paths[0]['destination']:
+        print(f"  {term.role}: {paths[0]['destination']}")
+```

docs/dcim.md

@@ -105,8 +105,6 @@ Several DCIM models support cable path tracing through the `trace()` method.
 - PowerPorts
 - PowerOutlets
 - PowerFeeds
-- FrontPorts
-- RearPorts
 
 **Example:**
 ```python
@@ -135,3 +133,47 @@ console_trace = console.trace()
 power_port = nb.dcim.power_ports.get(name='PSU1', device='server1')
 power_trace = power_port.trace()
 ```
+
+## Cable Path Tracing (Pass-Through Ports)
+
+Front ports and rear ports use the `paths()` method instead of `trace()`.
+
+**Models with cable path tracing:**
+- FrontPorts
+- RearPorts
+
+**Example:**
+```python
+# Get paths through a front port
+front_port = nb.dcim.front_ports.get(name='FrontPort1', device='patch-panel-1')
+paths = front_port.paths()
+
+# Each path contains origin, destination, and path segments
+for path_info in paths:
+    print(f"Origin: {path_info['origin']}")
+    print(f"Destination: {path_info['destination']}")
+    print("Path segments:")
+    for segment in path_info['path']:
+        for obj in segment:
+            print(f"  - {obj}")
+
+# Get paths through a rear port
+rear_port = nb.dcim.rear_ports.get(name='RearPort1', device='patch-panel-1')
+rear_paths = rear_port.paths()
+
+# Access the complete path from origin to destination
+if rear_paths:
+    first_path = rear_paths[0]
+    if first_path['origin']:
+        print(f"Cable path starts at: {first_path['origin']}")
+    if first_path['destination']:
+        print(f"Cable path ends at: {first_path['destination']}")
+```
+
+**Path Structure:**
+
+The `paths()` method returns a list of dictionaries, where each dictionary represents a complete cable path:
+
+- `origin`: The starting endpoint of the path (Record object or None if unconnected)
+- `destination`: The ending endpoint of the path (Record object or None if unconnected)
+- `path`: A list of path segments, where each segment is a list of Record objects representing the components in that segment (cables, terminations, etc.)

mkdocs.yml

@@ -34,8 +34,9 @@ nav:
     - Endpoint: endpoint.md
     - Response: response.md
     - Request: request.md
-    - IPAM: ipam.md
+    - Circuits: circuits.md
     - DCIM: dcim.md
+    - IPAM: ipam.md
     - Virtualization: virtualization.md
   - Advanced Topics:
     - Advanced Usage: advanced.md

pynetbox/core/response.py

@@ -373,6 +373,55 @@ def __eq__(self, other):
             return self.__key__() == other.__key__()
         return NotImplemented
 
+    def _extract_app_endpoint(self, url):
+        """Extract app/endpoint from a NetBox API URL.
+
+        Extracts the app and endpoint portion from a URL like:
+            https://netbox/api/dcim/rear-ports/12761/
+        Returns:
+            String like "dcim/rear-ports"
+        """
+        app_endpoint = "/".join(
+            urlsplit(url).path[len(urlsplit(self.api.base_url).path) :].split("/")[1:3]
+        )
+        return app_endpoint
+
+    def _get_obj_class(self, url):
+        """Map API URL to corresponding Record class for cable tracing.
+
+        Used by TraceableRecord and PathableRecord to deserialize objects
+        encountered in cable trace/path responses.
+        """
+        # Import here to avoid circular dependency
+        from pynetbox.models.circuits import CircuitTerminations
+        from pynetbox.models.dcim import (
+            Cables,
+            ConsolePorts,
+            ConsoleServerPorts,
+            FrontPorts,
+            Interfaces,
+            PowerFeeds,
+            PowerOutlets,
+            PowerPorts,
+            RearPorts,
+        )
+
+        uri_to_obj_class_map = {
+            "circuits/circuit-terminations": CircuitTerminations,
+            "dcim/cables": Cables,
+            "dcim/console-ports": ConsolePorts,
+            "dcim/console-server-ports": ConsoleServerPorts,
+            "dcim/front-ports": FrontPorts,
+            "dcim/interfaces": Interfaces,
+            "dcim/power-feeds": PowerFeeds,
+            "dcim/power-outlets": PowerOutlets,
+            "dcim/power-ports": PowerPorts,
+            "dcim/rear-ports": RearPorts,
+        }
+
+        app_endpoint = self._extract_app_endpoint(url)
+        return uri_to_obj_class_map.get(app_endpoint, Record)
+
     def _add_cache(self, item):
         key, value = item
         self._init_cache.append((key, get_return(value)))
@@ -647,6 +696,64 @@ def delete(self):
         return True if req.delete() else False
 
 
+class PathableRecord(Record):
+    """Record class for objects that support cable path tracing via /paths endpoint.
+
+    Front ports, rear ports, and circuit terminations use the /paths endpoint
+    to show complete cable paths from origin to destination.
+    """
+
+    def _build_endpoint_object(self, endpoint_data):
+        if not endpoint_data:
+            return None
+
+        return_obj_class = self._get_obj_class(endpoint_data["url"])
+        return return_obj_class(endpoint_data, self.endpoint.api, self.endpoint)
+
+    def paths(self):
+        """Return all cable paths traversing this pass-through port.
+
+        Returns a list of dictionaries, each containing:
+        - origin: The starting endpoint of the path (or None if not connected)
+        - destination: The ending endpoint of the path (or None if not connected)
+        - path: List of path segments, where each segment is a list of Record objects
+                (similar to the trace() endpoint structure)
+        """
+        req = Request(
+            key=str(self.id) + "/paths",
+            base=self.endpoint.url,
+            token=self.api.token,
+            http_session=self.api.http_session,
+        ).get()
+
+        ret = []
+        for path_data in req:
+            path_segments = []
+            for segment_data in path_data.get("path", []):
+                segment_objects = []
+                if isinstance(segment_data, list):
+                    for item_data in segment_data:
+                        segment_obj = self._build_endpoint_object(item_data)
+                        if segment_obj:
+                            segment_objects.append(segment_obj)
+                else:
+                    segment_obj = self._build_endpoint_object(segment_data)
+                    if segment_obj:
+                        segment_objects.append(segment_obj)
+                path_segments.append(segment_objects)
+
+            origin = self._build_endpoint_object(path_data.get("origin"))
+            destination = self._build_endpoint_object(path_data.get("destination"))
+
+            ret.append({
+                "origin": origin,
+                "destination": destination,
+                "path": path_segments,
+            })
+
+        return ret
+
+
 class GenericListObject:
     def __init__(self, record):
         from pynetbox.models.mapper import TYPE_CONTENT_MAPPER