feat(endpoint): add SVG support for rack elevation endpoint

Author: NeverBehave

docs/advanced.md

@@ -130,4 +130,51 @@ with open('/path/to/image.png', 'rb') as f:
     )
 ```
 
-The tuple format is `(filename, file_object)` or `(filename, file_object, content_type)`.
+The tuple format is `(filename, file_object)` or `(filename, file_object, content_type)`.
+
+# Multi-Format Responses
+
+Some endpoints support multiple response formats. The rack elevation endpoint can return both JSON data and SVG diagrams.
+
+## Getting Rack Elevation as JSON
+
+By default, the elevation endpoint returns JSON data as a list of rack unit objects:
+
+```python
+import pynetbox
+
+nb = pynetbox.api(
+    'http://localhost:8000',
+    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
+)
+
+rack = nb.dcim.racks.get(123)
+
+# Returns list of RU objects (default JSON response)
+units = rack.elevation.list()
+for unit in units:
+    print(unit.id, unit.name)
+```
+
+## Getting Rack Elevation as SVG
+
+Use the `render='svg'` parameter to get a graphical SVG diagram:
+
+```python
+rack = nb.dcim.racks.get(123)
+
+# Returns raw SVG string
+svg_diagram = rack.elevation.list(render='svg')
+print(svg_diagram)  # '<svg xmlns="http://www.w3.org/2000/svg">...</svg>'
+
+# Save to file
+with open('rack-elevation.svg', 'w') as f:
+    f.write(svg_diagram)
+```
+
+## Supported Formats
+
+The elevation endpoint supports:
+- `render='json'` - Explicitly request JSON (same as default)
+- `render='svg'` - Get SVG diagram
+- Unsupported formats raise `ValueError`

pynetbox/core/endpoint.py

@@ -668,3 +668,54 @@ def create(self, data=None):
 class RODetailEndpoint(DetailEndpoint):
     def create(self, data):
         raise NotImplementedError("Writes are not supported for this endpoint.")
+
+
+class ROMultiFormatDetailEndpoint(RODetailEndpoint):
+    """Read-only detail endpoint supporting multiple response formats.
+
+    Handles endpoints that return data in different formats based on
+    query parameters. Supports both structured data (JSON) and raw formats
+    (e.g., SVG).
+
+    The endpoint inspects the 'render' parameter to determine response format:
+    - No parameter or render='json': Returns structured JSON data
+    - render='svg': Returns raw SVG content
+
+    ## Examples
+
+    ```python
+    rack = nb.dcim.racks.get(123)
+    rack.elevation.list()  # Returns: list of rack unit objects
+    rack.elevation.list(render='svg')  # Returns: SVG string
+    rack.elevation.list(render='json')  # Returns: list of rack unit objects
+    ```
+    """
+
+    def list(self, **kwargs):
+        """Returns data in the requested format.
+
+        ## Parameters
+
+        * **kwargs**: Key/value pairs that get converted into URL
+            parameters. Supports 'render' parameter for format selection.
+
+        ## Returns
+
+        - If render is non-JSON format: Raw content (string)
+        - If render is 'json' or absent: Structured data (list/generator)
+        """
+        # Check if non-JSON format requested
+        render_format = kwargs.get("render")
+        if render_format == "svg":
+            # Pass expect_json=False for raw SVG response
+            req = Request(**self.request_kwargs, expect_json=False).get(
+                add_params=kwargs
+            )
+            # Return raw content for non-JSON formats
+            return next(req)
+
+        if render_format != "json" and render_format is not None:
+            raise ValueError(f"Unsupported render format: {render_format}")
+
+        # Return structured JSON response via parent class
+        return super().list(**kwargs)

pynetbox/core/query.py

@@ -200,6 +200,7 @@ def __init__(
         key=None,
         token=None,
         threading=False,
+        expect_json=True,
     ):
         """Instantiates a new Request object.
 
@@ -211,6 +212,9 @@ def __init__(
             In (e.g. /api/dcim/devices/?name='test') 'name': 'test'
             would be in the filters dict.
         * **key** (int, optional): Database id of the item being queried.
+        * **expect_json** (bool, optional): If True, expects JSON response
+            and sets appropriate Accept header. If False, expects raw content
+            (e.g., SVG, XML) and returns text. Defaults to True.
         """
         self.base = self.normalize_url(base)
         self.filters = filters or None
@@ -221,6 +225,9 @@ def __init__(
         self.threading = threading
         self.limit = limit
         self.offset = offset
+        self.expect_json = expect_json
+        # Response Attributes
+        self.count = None
 
     def get_openapi(self):
         """Gets the OpenAPI Spec."""
@@ -304,7 +311,12 @@ def _make_call(self, verb="get", url_override=None, add_params=None, data=None):
         files = None
         # Verbs that support request bodies with file uploads
         body_verbs = ("post", "put", "patch")
-        headers = {"accept": "application/json"}
+
+        # Set Accept header based on expected response type
+        if self.expect_json:
+            headers = {"accept": "application/json"}
+        else:
+            headers = {"accept": "*/*"}
 
         # Extract files from data for applicable verbs
         if data is not None and verb in body_verbs:
@@ -316,7 +328,7 @@ def _make_call(self, verb="get", url_override=None, add_params=None, data=None):
         )
 
         if should_be_json_body:
-            headers = {"Content-Type": "application/json"}
+            headers["Content-Type"] = "application/json"
 
         if self.token:
             headers["authorization"] = "Token {}".format(self.token)
@@ -350,10 +362,15 @@ def _make_call(self, verb="get", url_override=None, add_params=None, data=None):
             else:
                 raise RequestError(req)
         elif req.ok:
-            try:
-                return req.json()
-            except json.JSONDecodeError:
-                raise ContentError(req)
+            # Parse response based on expected type
+            if self.expect_json:
+                try:
+                    return req.json()
+                except json.JSONDecodeError:
+                    raise ContentError(req)
+            else:
+                # Return raw text for non-JSON responses
+                return req.text
         else:
             raise RequestError(req)
 

pynetbox/models/dcim.py

@@ -16,7 +16,11 @@
 
 from urllib.parse import urlsplit
 
-from pynetbox.core.endpoint import DetailEndpoint, RODetailEndpoint
+from pynetbox.core.endpoint import (
+    DetailEndpoint,
+    RODetailEndpoint,
+    ROMultiFormatDetailEndpoint,
+)
 from pynetbox.core.query import Request
 from pynetbox.core.response import JsonField, Record
 from pynetbox.models.circuits import Circuits, CircuitTerminations
@@ -230,22 +234,26 @@ def units(self):
     def elevation(self):
         """Represents the ``elevation`` detail endpoint.
 
-        Returns a DetailEndpoint object that is the interface for
-        viewing response from the elevation endpoint updated in
-        Netbox version 2.8.
+        Returns a multi-format endpoint supporting both JSON and SVG responses.
+        The elevation endpoint provides rack unit information and can render
+        graphical elevation views.
 
         ## Returns
-        DetailEndpoint object.
+        ROMultiFormatDetailEndpoint object supporting JSON and SVG formats.
 
         ## Examples
 
         ```python
         rack = nb.dcim.racks.get(123)
+
+        # Get rack units as JSON (list of RU objects)
         rack.elevation.list()
-        # {"get_facts": {"interface_list": ["ge-0/0/0"]}}
+
+        # Get elevation as SVG diagram
+        svg = rack.elevation.list(render='svg')
         ```
         """
-        return RODetailEndpoint(self, "elevation", custom_return=RUs)
+        return ROMultiFormatDetailEndpoint(self, "elevation", custom_return=RUs)
 
 
 class Termination(Record):

tests/unit/test_multiformat_endpoint.py

@@ -0,0 +1,144 @@
+"""Tests for ROMultiFormatDetailEndpoint."""
+
+import unittest
+from unittest.mock import Mock, patch
+
+import pynetbox
+from pynetbox.core.endpoint import ROMultiFormatDetailEndpoint
+
+
+class ROMultiFormatDetailEndpointTestCase(unittest.TestCase):
+    """Test cases for ROMultiFormatDetailEndpoint class."""
+
+    def setUp(self):
+        """Set up test fixtures."""
+        self.nb = pynetbox.api("http://localhost:8000", token="test-token")
+
+    def test_list_returns_json_by_default(self):
+        """list() without render parameter returns JSON data."""
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value={"id": 123, "name": "Test Rack"},
+        ):
+            rack = self.nb.dcim.racks.get(123)
+
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value=[
+                {"id": 1, "name": "U1"},
+                {"id": 2, "name": "U2"},
+            ],
+        ):
+            result = rack.elevation.list()
+            # Should return generator that yields dict items
+            result_list = list(result)
+            self.assertEqual(len(result_list), 2)
+            # Verify custom_return was applied (RUs objects)
+            self.assertTrue(hasattr(result_list[0], "id"))
+
+    def test_list_with_render_svg_returns_raw_string(self):
+        """list(render='svg') returns raw SVG string."""
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value={"id": 123, "name": "Test Rack"},
+        ):
+            rack = self.nb.dcim.racks.get(123)
+
+        svg_content = '<svg xmlns="http://www.w3.org/2000/svg"><rect/></svg>'
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value=svg_content,
+        ):
+            result = rack.elevation.list(render="svg")
+            # Should return raw string, not wrapped in list
+            self.assertIsInstance(result, str)
+            self.assertEqual(result, svg_content)
+            self.assertIn("<svg", result)
+
+    def test_list_with_render_json_returns_json_data(self):
+        """list(render='json') explicitly returns JSON data."""
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value={"id": 123, "name": "Test Rack"},
+        ):
+            rack = self.nb.dcim.racks.get(123)
+
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value=[
+                {"id": 1, "name": "U1"},
+                {"id": 2, "name": "U2"},
+            ],
+        ):
+            result = rack.elevation.list(render="json")
+            # Should return JSON like default behavior
+            result_list = list(result)
+            self.assertEqual(len(result_list), 2)
+            self.assertTrue(hasattr(result_list[0], "id"))
+
+    def test_svg_response_not_processed_by_custom_return(self):
+        """SVG response bypasses custom_return transformation."""
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value={"id": 123, "name": "Test Rack"},
+        ):
+            rack = self.nb.dcim.racks.get(123)
+
+        svg_content = "<svg><text>Test</text></svg>"
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value=svg_content,
+        ):
+            result = rack.elevation.list(render="svg")
+            # Result should be raw string, not Record object
+            self.assertIsInstance(result, str)
+            self.assertFalse(hasattr(result, "id"))
+            self.assertFalse(hasattr(result, "serialize"))
+
+    def test_empty_response_with_svg(self):
+        """Empty SVG response is handled correctly."""
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value={"id": 123, "name": "Test Rack"},
+        ):
+            rack = self.nb.dcim.racks.get(123)
+
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value="",
+        ):
+            result = rack.elevation.list(render="svg")
+            # Should return empty string
+            self.assertIsInstance(result, str)
+            self.assertEqual(result, "")
+
+    def test_create_raises_not_implemented(self):
+        """create() raises NotImplementedError (read-only endpoint)."""
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value={"id": 123, "name": "Test Rack"},
+        ):
+            rack = self.nb.dcim.racks.get(123)
+
+        # ROMultiFormatDetailEndpoint should be read-only
+        with self.assertRaises(NotImplementedError):
+            rack.elevation.create({"data": "test"})
+
+    def test_unsupported_render_format_raises_error(self):
+        """Unsupported render format raises ValueError."""
+        with patch(
+            "pynetbox.core.query.Request._make_call",
+            return_value={"id": 123, "name": "Test Rack"},
+        ):
+            rack = self.nb.dcim.racks.get(123)
+
+        # Unsupported render formats should raise ValueError
+        with self.assertRaises(ValueError) as context:
+            rack.elevation.list(render="png")
+
+        self.assertIn("Unsupported render format", str(context.exception))
+        self.assertIn("png", str(context.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()