Reorder a template among its siblings in the Server ADR (#367)

User story in ADO:
https://tfs.ansys.com:8443/tfs/ANSYS_Development/Portfolio/_boards/board/t/Nexus/Stories/?workitem=1234450

This PR fulfills the functionality of getting and setting orders of a
target template in the server object level. Higher level wrapper in
`Report` can be in another PR after this PR is approved.

Testing is missing for now in case there will be some design changes.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: zhang-yuanrui

src/ansys/dynamicreporting/core/utils/exceptions.py

@@ -57,6 +57,14 @@ class TemplateEditorJSONLoadingError(RuntimeError):
     """Raised for errors when loading a JSON file for the template editor"""
 
 
+class TemplateDoesNotExist(RuntimeError):
+    """Raised when the template is not found"""
+
+
+class TemplateReorderOutOfBounds(RuntimeError):
+    """Raised when a template is reordered to be out of the size of the children"""
+
+
 def raise_bad_request_error(response):
     """
     Generates bad request error message and raises an exception.

src/ansys/dynamicreporting/core/utils/report_objects.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from ast import literal_eval
 import base64
 import copy
@@ -14,12 +16,11 @@
 import uuid
 import weakref
 
-from PIL import Image
 import dateutil
 import dateutil.parser
 import pytz
 
-from . import extremely_ugly_hacks, report_utils
+from . import exceptions, extremely_ugly_hacks, report_utils
 from .encoders import PayloaddataEncoder
 
 try:
@@ -1624,6 +1625,45 @@ def get_html(self):
         else:
             raise ValueError(f"Error: HTML not supported on the report type {self.report_type}")
 
+    def reorder_child(self, target_child_template: str | TemplateREST, new_position: int) -> None:
+        """
+        Reorder the template.guid in parent.children to the specified position.
+
+        Parameters
+        ----------
+        target_child_template : str | TemplateREST
+            The child template to reorder. This can be either the GUID of the template (as a string)
+            or a TemplateREST object.
+        new_position : int
+            The new position in the parent's children list where the template should be placed.
+
+        Raises
+        ------
+        TemplateReorderOutOfBoundError
+            If the specified position is out of bounds.
+        ValueError
+            If the target_child_template is not found in the parent's children list.
+        """
+        children_size = len(self.children)
+        if new_position < 0 or new_position >= children_size:
+            raise exceptions.TemplateReorderOutOfBounds(
+                f"The specified position {new_position} is out of bounds. "
+                f"Valid range: [0, {len(self.children)})"
+            )
+
+        target_guid = (
+            target_child_template
+            if isinstance(target_child_template, str)
+            else target_child_template.guid
+        )
+
+        if target_guid not in self.children:
+            raise exceptions.TemplateDoesNotExist(
+                f"Template with GUID '{target_guid}' is not found in the parent's children list."
+            )
+        self.children.remove(target_guid)
+        self.children.insert(new_position, target_guid)
+
 
 class LayoutREST(TemplateREST):
     """Representation of the common Layout Template."""

tests/test_report_objects.py

@@ -392,6 +392,39 @@ def test_templaterest_fields() -> None:
     assert succ_a and succ_four and succ_five
 
 
+@pytest.mark.ado_test
+def test_templaterest_set_order() -> None:
+    # Create a TemplateREST object
+    template = ro.TemplateREST()
+    template.children = ["guid1", "guid2", "guid3"]
+
+    # Test reordering a child template to a valid position
+    template.reorder_child("guid2", 0)
+    assert template.children == ["guid2", "guid1", "guid3"]
+
+    # Test reordering a child template to another valid position
+    template.reorder_child("guid2", 2)
+    assert template.children == ["guid1", "guid3", "guid2"]
+
+    # Test reordering using a TemplateREST object instead of a string
+    child_template = ro.TemplateREST()
+    child_template.guid = "guid3"
+    template.reorder_child(child_template, 0)
+    assert template.children == ["guid3", "guid1", "guid2"]
+
+    # Test invalid position (out of bounds)
+    try:
+        template.reorder_child("guid1", 5)
+    except ro.exceptions.TemplateReorderOutOfBounds as e:
+        assert "out of bounds" in str(e)
+
+    # Test invalid GUID (not in children)
+    try:
+        template.reorder_child("invalid_guid", 1)
+    except ro.exceptions.TemplateDoesNotExist as e:
+        assert "not found in the parent's children list" in str(e)
+
+
 @pytest.mark.ado_test
 def test_templaterest_filter() -> None:
     a = ro.TemplateREST()