feat: grpc common layer architecture, bodies stub and admin stub implementation (#1867)

Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

doc/changelog.d/1867.added.md

@@ -0,0 +1 @@
+grpc common layer architecture, bodies stub and admin stub implementation

doc/source/conf.py

@@ -279,6 +279,7 @@ def intersphinx_pyansys_geometry(switcher_version: str):
     "design.grid",
     "config.cache",
     "design.fa-build",
+    "toc.not_included",  # Caused by the autoapi extension and the "_grpc" folder
 ]
 
 # Examples gallery customization

src/ansys/geometry/core/_grpc/_services/_service.py

@@ -0,0 +1,116 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import grpc
+
+from .._version import GeometryApiProtos, set_proto_version
+from .base.bodies import GRPCBodyService
+
+
+class _GRPCServices:
+    """
+    Placeholder for the gRPC services (i.e. stubs).
+
+    Notes
+    -----
+    This class provides a unified interface to access the different
+    gRPC services available in the Geometry API. It allows for easy
+    switching between different versions of the API by using the
+    `version` parameter in the constructor. The services are lazy-loaded
+    to avoid unnecessary imports and to improve performance.
+
+    Parameters
+    ----------
+    channel : grpc.Channel
+        The gRPC channel to the server.
+    version : GeometryApiProtos | str | None
+        The version of the gRPC API protocol to use. If None, the latest
+        version is used.
+    """
+
+    def __init__(self, channel: grpc.Channel, version: GeometryApiProtos | str | None = None):
+        """
+        Initialize the GRPCServices class.
+
+        Parameters
+        ----------
+        channel : grpc.Channel
+            The gRPC channel to the server.
+        version : GeometryApiProtos | str | None
+            The version of the gRPC API protocol to use. If None, the latest
+            version is used.
+        """
+        # Set the proto version to be used
+        self.version = set_proto_version(channel, version)
+        self.channel = channel
+
+        # Lazy load all the services
+        self._admin = None
+        self._bodies = None
+
+    @property
+    def bodies(self) -> GRPCBodyService:
+        """
+        Get the body service for the specified version.
+
+        Returns
+        -------
+        BodyServiceBase
+            The body service for the specified version.
+        """
+        if not self._bodies:
+            # Import the appropriate body service based on the version
+            from .v0.bodies import GRPCBodyServiceV0
+            from .v1.bodies import GRPCBodyServiceV1
+
+            if self.version == GeometryApiProtos.V0:
+                self._bodies = GRPCBodyServiceV0(self.channel)
+            elif self.version == GeometryApiProtos.V1:
+                self._bodies = GRPCBodyServiceV1(self.channel)
+            else:
+                raise ValueError(f"Unsupported version: {self.version}")
+
+        return self._bodies
+
+    @property
+    def admin(self):
+        """
+        Get the admin service for the specified version.
+
+        Returns
+        -------
+        AdminServiceBase
+            The admin service for the specified version.
+        """
+        if not self._admin:
+            # Import the appropriate admin service based on the version
+            from .v0.admin import GRPCAdminServiceV0
+            from .v1.admin import GRPCAdminServiceV1
+
+            if self.version == GeometryApiProtos.V0:
+                self._admin = GRPCAdminServiceV0(self.channel)
+            elif self.version == GeometryApiProtos.V1:
+                self._admin = GRPCAdminServiceV1(self.channel)
+            else:
+                raise ValueError(f"Unsupported version: {self.version}")
+
+        return self._admin

src/ansys/geometry/core/_grpc/_services/base/admin.py

@@ -0,0 +1,50 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Module containing the admin service implementation (abstraction layer)."""
+
+from abc import ABC, abstractmethod
+
+import grpc
+
+
+class GRPCAdminService(ABC):
+    """Admin service for gRPC communication with the Geometry server.
+
+    Parameters
+    ----------
+    channel : grpc.Channel
+        The gRPC channel to the server.
+    """
+
+    def __init__(self, channel: grpc.Channel):
+        """Initialize the AdminServiceBase class."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_backend(self, **kwargs) -> dict:
+        """Get server information."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_logs(self, **kwargs) -> dict:
+        """Get server logs."""
+        pass  # pragma: no cover

src/ansys/geometry/core/_grpc/_services/base/bodies.py

@@ -0,0 +1,205 @@
+# Copyright (C) 2023 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Module containing the bodies service implementation (abstraction layer)."""
+
+from abc import ABC, abstractmethod
+
+import grpc
+
+
+class GRPCBodyService(ABC):
+    """Body service for gRPC communication with the Geometry server.
+
+    Parameters
+    ----------
+    channel : grpc.Channel
+        The gRPC channel to the server.
+    """
+
+    def __init__(self, channel: grpc.Channel):
+        """Initialize the BodyServiceBase class."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_sphere_body(self, **kwargs) -> dict:
+        """Create a sphere body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_extruded_body(self, **kwargs) -> dict:
+        """Create an extruded body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_sweeping_profile_body(self, **kwargs) -> dict:
+        """Create a sweeping profile body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_sweeping_chain(self, **kwargs) -> dict:
+        """Create a sweeping chain."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_extruded_body_from_face_profile(self, **kwargs) -> dict:
+        """Create an extruded body from a face profile."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_extruded_body_from_loft_profiles(self, **kwargs) -> dict:
+        """Create an extruded body from loft profiles."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_planar_body(self, **kwargs) -> dict:
+        """Create a planar body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_body_from_face(self, **kwargs) -> dict:
+        """Create a body from a face."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_surface_body(self, **kwargs) -> dict:
+        """Create a surface body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def create_surface_body_from_trimmed_curves(self, **kwargs) -> dict:
+        """Create a surface body from trimmed curves."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def translate(self, **kwargs) -> dict:
+        """Translate a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def delete(self, **kwargs) -> dict:
+        """Delete a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def is_suppressed(self, **kwargs) -> dict:
+        """Check if a body is suppressed."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_color(self, **kwargs) -> dict:
+        """Get the color of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_faces(self, **kwargs) -> dict:
+        """Get the faces of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_edges(self, **kwargs) -> dict:
+        """Get the edges of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_volume(self, **kwargs) -> dict:
+        """Get the volume of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_bounding_box(self, **kwargs) -> dict:
+        """Get the bounding box of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def set_assigned_material(self, **kwargs) -> dict:
+        """Set the assigned material of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_assigned_material(self, **kwargs) -> dict:
+        """Get the assigned material of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def set_name(self, **kwargs) -> dict:
+        """Set the name of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def set_fill_style(self, **kwargs) -> dict:
+        """Set the fill style of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def set_suppressed(self, **kwargs) -> dict:
+        """Set the suppressed state of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def set_color(self, **kwargs) -> dict:
+        """Set the color of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def rotate(self, **kwargs) -> dict:
+        """Rotate a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def scale(self, **kwargs) -> dict:
+        """Scale a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def mirror(self, **kwargs) -> dict:
+        """Mirror a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def map(self, **kwargs) -> dict:
+        """Map a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_collision(self, **kwargs) -> dict:
+        """Get the collision of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def copy(self, **kwargs) -> dict:
+        """Copy a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_tesellation(self, **kwargs) -> dict:
+        """Get the tessellation of a body."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_tesellation_with_options(self, **kwargs) -> dict:
+        """Get the tessellation of a body with options."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def boolean(self, **kwargs) -> dict:
+        """Boolean operation."""
+        pass  # pragma: no cover