deprecate: mark download_latent_parameters_json as deprecated

src/ansys/simai/core/data/geomai/workspaces.py

@@ -21,6 +21,7 @@
 # SOFTWARE.
 
 import json
+import warnings
 from typing import TYPE_CHECKING, BinaryIO, List, Optional, Union
 
 from ansys.simai.core.data.base import DataModel, Directory
@@ -29,10 +30,12 @@
     File,
     Filters,
     Identifiable,
+    Path,
     SizedIterator,
     get_id_from_identifiable,
     to_raw_filters,
 )
+from ansys.simai.core.errors import PySimAIDepreciationWarning
 from ansys.simai.core.utils.pagination import DataModelIterator
 
 if TYPE_CHECKING:
@@ -89,19 +92,44 @@ def set_as_current_workspace(self) -> None:
         self._client.geomai.current_workspace = self
 
     def download_latent_parameters_json(self, file: Optional[File] = None) -> Union[None, BinaryIO]:
-        """Download the json file containing the latent parameters for the model's training data.
+        """Download the JSON file containing the latent parameters for the model's training data.
+
+        Warning:
+            This feature is deprecated and will be retired in August 2026. Please use :py:meth:`~get_latent_parameters` instead.
 
         Args:
             file: Binary file-object or the path of the file to put the content into.
 
         Returns:
             ``None`` if a file is specified or a binary file-object otherwise.
         """
+        warnings.warn(
+            "`download_latent_parameters_json` is deprecated. Use 'get_latent_parameters' instead.",
+            PySimAIDepreciationWarning,
+            stacklevel=2,
+        )
+        # We don't use `get_latent_parameters` here because it doesn't return a binary file-object when file is None
         return self._client._api.download_geomai_workspace_latent_parameters(self.id, file)
 
-    def get_latent_parameters(self) -> dict[str, List[float]]:
-        """Get the dictionary mapping geometry names to their latent parameter vectors for the model's training data."""
-        data = self._client._api.download_geomai_workspace_latent_parameters(self.id, None)
+    def get_latent_parameters(
+        self,
+        file: Optional[File] = None,
+    ) -> Union[dict[str, List[float]], None, BinaryIO]:
+        """Get the mapping between geometry names and their latent parameter vectors for the model's training data.
+
+        Args:
+            file: Binary file-object or the path of the file to put the content into.
+
+        Returns:
+            ``None`` or a binary file-object if a file is specified or a dictionary mapping geometry names to latent parameter
+            vectors otherwise.
+        """
+        data = self._client._api.download_geomai_workspace_latent_parameters(self.id, file)
+        if file:
+            if isinstance(file, File) and not isinstance(file, (str, Path)):
+                return file
+            return data
+
         if data is None:
             return {}
         latent_parameters = json.loads(data.read().decode("utf-8"))

tests/geomai/test_geomai_workspaces.py

@@ -21,6 +21,7 @@
 # SOFTWARE.
 
 import json
+from io import BytesIO
 from typing import TYPE_CHECKING
 from urllib.parse import urlencode
 
@@ -93,6 +94,28 @@ def test_geomai_workspace_get_latent_parameters(simai_client, httpx_mock):
     assert latent_parameters == {"geometry1": [1, 2, 3]}
 
 
+def test_geomai_workspace_get_latent_parameters_returns_binary_file_when_file_set(
+    simai_client, httpx_mock
+):
+    workspace: GeomAIWorkspace = simai_client.geomai._workspace_directory._model_from(
+        {"id": "abc123", "name": "HL3"}
+    )
+
+    httpx_mock.add_response(
+        method="GET",
+        url=f"https://test.test/geomai/workspaces/{workspace.id}/model/latent-parameters-json",
+        text='{"geometry1": [1,2,3]}',
+        status_code=200,
+    )
+    target_file = BytesIO()
+    returned_file = BytesIO(b'{"geometry1": [1,2,3]}')
+
+    latent_parameters = workspace.get_latent_parameters(target_file)
+
+    assert isinstance(latent_parameters, BytesIO)
+    assert latent_parameters.getvalue() == returned_file.getvalue()
+
+
 def test_get_workspace_model_configuration(mocker, simai_client, httpx_mock, training_data_factory):
     workspace: GeomAIWorkspace = simai_client.geomai._workspace_directory._model_from(
         {"id": "0011", "name": "riri"}