Allow marking 'supported_since' on class level (#604)

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

On all existing classes, the `_SUPPORTED_SINCE` attribute is set to `"24.2"`.

Author: greschd

src/ansys/acp/core/_server/direct.py

@@ -22,6 +22,7 @@
 
 import dataclasses
 import os
+import pathlib
 import subprocess
 from typing import TextIO
 
@@ -103,6 +104,10 @@ def start(self) -> None:
         stdout_file = self._config.stdout_file
         stderr_file = self._config.stderr_file
 
+        binary = pathlib.Path(self._config.binary_path)
+        if not binary.exists():
+            raise FileNotFoundError(f"Binary not found: '{binary}'")
+
         port = find_free_ports()[0]
         self._url = f"localhost:{port}"
         self._stdout = open(stdout_file, mode="w", encoding="utf-8")

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

@@ -26,6 +26,7 @@
 from typing import Any, Concatenate, Generic, TypeVar
 
 from grpc import Channel
+from packaging.version import parse as parse_version
 from typing_extensions import ParamSpec, Self
 
 from ansys.api.acp.v0.base_pb2 import CollectionPath, DeleteRequest, ListRequest
@@ -302,6 +303,14 @@ def define_mutable_mapping(
     """Define a mutable mapping of child tree objects."""
 
     def collection_property(self: ParentT) -> MutableMapping[CreatableValueT]:
+        if self._server_version is not None:
+            if self._server_version < parse_version(object_class._SUPPORTED_SINCE):
+                raise RuntimeError(
+                    f"The '{object_class.__name__}' object is only supported since version "
+                    f"{object_class._SUPPORTED_SINCE} of the ACP gRPC server. The current server version is "
+                    f"{self._server_version}."
+                )
+
         return MutableMapping._initialize_with_cache(
             server_wrapper=self._server_wrapper,
             collection_path=CollectionPath(

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

@@ -29,6 +29,7 @@
 
 from collections.abc import Callable
 from functools import reduce
+import sys
 from typing import TYPE_CHECKING, Any, TypeVar
 
 from google.protobuf.message import Message
@@ -91,6 +92,27 @@ def mark_grpc_properties(cls: T) -> T:
         if name not in props_unique:
             props_unique.append(name)
     cls._GRPC_PROPERTIES = tuple(props_unique)
+
+    # The 'mark_grpc_properties' decorator is also used on intermediate base
+    # classes which do not have the '_SUPPORTED_SINCE' attribute. We only want
+    # to add the version information to the final class.
+    if hasattr(cls, "_SUPPORTED_SINCE"):
+        if isinstance(cls.__doc__, str):
+            # When adding to the docstring, we need to match the existing
+            # indentation of the docstring (except the first line).
+            # See PEP 257 'Handling Docstring Indentation'.
+            # Alternatively, we could strip the common indentation from the
+            # docstring.
+            indent = sys.maxsize
+            for line in cls.__doc__.splitlines()[1:]:
+                stripped = line.lstrip()
+                if stripped:  # ignore empty lines
+                    indent = min(indent, len(line) - len(stripped))
+            if indent == sys.maxsize:
+                indent = 0
+            cls.__doc__ += (
+                f"\n\n{indent * ' '}*Added in ACP server version {cls._SUPPORTED_SINCE}.*\n"
+            )
     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
 
     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/analysis_ply.py

@@ -105,6 +105,7 @@ class AnalysisPly(ReadOnlyTreeObject, IdTreeObject):
 
     _COLLECTION_LABEL = "analysis_plies"
     _OBJECT_INFO_TYPE = analysis_ply_pb2.ObjectInfo
+    _SUPPORTED_SINCE = "24.2"
 
     def _create_stub(self) -> analysis_ply_pb2_grpc.ObjectServiceStub:
         return analysis_ply_pb2_grpc.ObjectServiceStub(self._channel)

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

@@ -76,6 +76,7 @@ class TreeObjectBase(ObjectCacheMixin, GrpcObjectBase):
 
     _COLLECTION_LABEL: str
     _OBJECT_INFO_TYPE: type[ObjectInfo]
+    _SUPPORTED_SINCE: str
 
     _pb_object: ObjectInfo
     name: ReadOnlyProperty[str]
@@ -328,6 +329,13 @@ def store(self: Self, parent: TreeObject) -> None:
             Parent object to store the object under.
         """
         self._server_wrapper_store = parent._server_wrapper
+        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)

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

@@ -91,6 +91,7 @@ class BooleanSelectionRule(CreatableTreeObject, IdTreeObject):
     _COLLECTION_LABEL = "boolean_selection_rules"
     _OBJECT_INFO_TYPE = boolean_selection_rule_pb2.ObjectInfo
     _CREATE_REQUEST_TYPE = boolean_selection_rule_pb2.CreateRequest
+    _SUPPORTED_SINCE = "24.2"
 
     def __init__(
         self,

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

@@ -49,6 +49,7 @@ class CADComponent(ReadOnlyTreeObject, IdTreeObject):
     __slots__: Iterable[str] = tuple()
     _COLLECTION_LABEL = "cad_components"
     _OBJECT_INFO_TYPE = cad_component_pb2.ObjectInfo
+    _SUPPORTED_SINCE = "24.2"
 
     def _create_stub(self) -> cad_component_pb2_grpc.ObjectServiceStub:
         return cad_component_pb2_grpc.ObjectServiceStub(self._channel)

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

@@ -108,6 +108,7 @@ class CADGeometry(CreatableTreeObject, IdTreeObject):
     _COLLECTION_LABEL = "cad_geometries"
     _OBJECT_INFO_TYPE = cad_geometry_pb2.ObjectInfo
     _CREATE_REQUEST_TYPE = cad_geometry_pb2.CreateRequest
+    _SUPPORTED_SINCE = "24.2"
 
     def __init__(
         self,