diff --git a/docs/src/rms_oneliners.rst b/docs/src/rms_oneliners.rst index 08266c5a3..63e30e42b 100644 --- a/docs/src/rms_oneliners.rst +++ b/docs/src/rms_oneliners.rst @@ -20,11 +20,11 @@ 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}") @@ -32,7 +32,7 @@ Most ``dataio`` settings are here defaulted, but some keys can be altered option .. code-block:: python - outfiles = export_rms_volumetrics( + outfiles = export_volumetrics( project, "Geogrid", "geogrid_volumes", diff --git a/src/fmu/dataio/export/_decorators.py b/src/fmu/dataio/export/_decorators.py new file mode 100644 index 000000000..0cb2082aa --- /dev/null +++ b/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 diff --git a/src/fmu/dataio/export/rms/__init__.py b/src/fmu/dataio/export/rms/__init__.py index 5fcbf3b16..7ee29e580 100644 --- a/src/fmu/dataio/export/rms/__init__.py +++ b/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"] diff --git a/src/fmu/dataio/export/rms/volumetrics.py b/src/fmu/dataio/export/rms/volumetrics.py index da81aa427..100aed45f 100644 --- a/src/fmu/dataio/export/rms/volumetrics.py +++ b/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) diff --git a/tests/test_export_rms/test_export_rms_volumetrics.py b/tests/test_export_rms/test_export_rms_volumetrics.py index 20fd40746..882d1614f 100644 --- a/tests/test_export_rms/test_export_rms_volumetrics.py +++ b/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()