FIX, DEP: rename from export_rms_volumetrics to export_volumetrics

docs/src/rms_oneliners.rst

@@ -20,19 +20,19 @@ Example:
 
 .. code-block:: python
 
-    from fmu.dataio.export.rms import export_rms_volumetrics
+    from fmu.dataio.export.rms import export_volumetrics
     ...
 
     # here 'Geogrid' is the grid model name, and 'geogrid_volumes' is the name of the volume job
-    outfiles = export_rms_volumetrics(project, "Geogrid", "geogrid_volumes")
+    outfiles = export_volumetrics(project, "Geogrid", "geogrid_volumes")
 
     print(f"Output volumes to {outfiles}")
 
 Most ``dataio`` settings are here defaulted, but some keys can be altered optionally, e.g.:
 
 .. code-block:: python
 
-    outfiles = export_rms_volumetrics(
+    outfiles = export_volumetrics(
         project,
         "Geogrid",
         "geogrid_volumes",

src/fmu/dataio/export/_decorators.py

@@ -0,0 +1,17 @@
+import warnings
+from functools import wraps
+
+
+def experimental(func):  # type: ignore
+    """Decorator to mark functions as experimental."""
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):  # type: ignore
+        warnings.warn(
+            f"{func.__name__} is experimental and may change in future versions.",
+            UserWarning,
+            stacklevel=2,
+        )
+        return func(*args, **kwargs)
+
+    return wrapper

src/fmu/dataio/export/rms/__init__.py

@@ -1,3 +1,3 @@
-from .volumetrics import export_rms_volumetrics
+from .volumetrics import export_rms_volumetrics, export_volumetrics
 
-__all__ = ["export_rms_volumetrics"]
+__all__ = ["export_volumetrics", "export_rms_volumetrics"]

src/fmu/dataio/export/rms/volumetrics.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Final
@@ -12,6 +13,7 @@
 from fmu.config.utilities import yaml_load
 from fmu.dataio._logging import null_logger
 
+from .._decorators import experimental
 from ._conditional_rms_imports import import_rms_package
 
 _modules = import_rms_package()
@@ -191,7 +193,8 @@ def export(self) -> dict[str, str]:
         return self._export_volume_table()
 
 
-def export_rms_volumetrics(
+@experimental
+def export_volumetrics(
     project: Any,
     grid_name: str,
     volume_job_name: str,
@@ -228,6 +231,9 @@ def export_rms_volumetrics(
         classification: Optional. Use 'internal' or 'restricted' (default).
         workflow: Optional. Information about the work flow; defaulted to
             'rms volumetrics'.
+
+    Note:
+        This function is experimental and may change in future versions.
     """
 
     return _ExportVolumetricsRMS(
@@ -242,3 +248,16 @@ def export_rms_volumetrics(
         classification=classification,
         workflow=workflow,
     ).export()
+
+
+# keep the old name for now but not log (will be removed soon as we expect close to
+# zero usage so far)
+def export_rms_volumetrics(*args, **kwargs) -> dict[str, str]:  # type: ignore
+    """Deprecated function. Use export_volumetrics instead."""
+    warnings.warn(
+        "export_rms_volumetrics is deprecated and will be removed in a future release. "
+        "Use export_volumetrics instead.",
+        FutureWarning,
+        stacklevel=2,
+    )
+    return export_volumetrics(*args, **kwargs)

tests/test_export_rms/test_export_rms_volumetrics.py

@@ -60,11 +60,11 @@ def test_rms_volumetrics_export_function(
 ):
     """Test the public function."""
 
-    from fmu.dataio.export.rms import export_rms_volumetrics
+    from fmu.dataio.export.rms import export_volumetrics
 
     os.chdir(rmssetup_with_fmuconfig)
 
-    result = export_rms_volumetrics(mock_project_variable, "Geogrid", "geogrid_volume")
+    result = export_volumetrics(mock_project_variable, "Geogrid", "geogrid_volume")
     vol_table_file = result["volume_table"]
 
     assert Path(vol_table_file).is_file()