Allow marking 'supported_since' on class level

Add a '_SUPPORTED_SINCE' class attribute to the 'GrpcObjectBase'
class, which has two effects:
- upon storing an object, check the server version and raise an
  appropriate exception if the server version is too low
- in the 'mark_grpc_properties' class decorator, add a line at the
  end of the class docstring indicating the server version at which
  the class was introduced

Author: greschd

src/ansys/acp/core/_tree_objects/_grpc_helpers/property_helper.py

@@ -91,6 +91,9 @@ def mark_grpc_properties(cls: T) -> T:
         if name not in props_unique:
             props_unique.append(name)
     cls._GRPC_PROPERTIES = tuple(props_unique)
+    if cls._SUPPORTED_SINCE is not None:
+        if isinstance(cls.__doc__, str):
+            cls.__doc__ += f"\n\nSupported since ACP gRPC server version {cls._SUPPORTED_SINCE}."
     return cls
 
 

src/ansys/acp/core/_tree_objects/_grpc_helpers/protocols.py

@@ -151,6 +151,7 @@ class GrpcObjectBase(Protocol):
 
     __slots__: Iterable[str] = tuple()
     _GRPC_PROPERTIES: tuple[str, ...] = tuple()
+    _SUPPORTED_SINCE: str | None = None
 
     def __str__(self) -> str:
         string_items = []

src/ansys/acp/core/_tree_objects/_grpc_helpers/supported_since.py

@@ -45,10 +45,10 @@ def supported_since(
 
     Parameters
     ----------
-    version : Optional[str]
+    version :
         The server version since which the method is supported. If ``None``, the
         decorator does nothing.
-    err_msg_tpl : Optional[str]
+    err_msg_tpl :
         A custom error message template. If ``None``, a default error message is used.
     """
     if version is None:
@@ -69,7 +69,7 @@ def inner(self: T, /, *args: P.args, **kwargs: P.kwargs) -> R:
                 if server_version < required_version:
                     if err_msg_tpl is None:
                         err_msg = (
-                            f"The method '{func.__name__}' is only supported since version {version} "
+                            f"The '{func.__name__}' method is only supported since version {version} "
                             f"of the ACP gRPC server. The current server version is {server_version}."
                         )
                     else:

src/ansys/acp/core/_tree_objects/base.py

@@ -328,6 +328,14 @@ def store(self: Self, parent: TreeObject) -> None:
             Parent object to store the object under.
         """
         self._server_wrapper_store = parent._server_wrapper
+        if self._SUPPORTED_SINCE is not None:
+            assert self._server_version is not None
+            if self._server_version < parse_version(self._SUPPORTED_SINCE):
+                raise RuntimeError(
+                    f"The '{type(self).__name__}' object is only supported since version "
+                    f"{self._SUPPORTED_SINCE} of the ACP gRPC server. The current server version is "
+                    f"{self._server_version}."
+                )
 
         collection_path = CollectionPath(
             value=_rp_join(parent._resource_path.value, self._COLLECTION_LABEL)