experimental¶

earthkit.utils.decorators.experimental(obj=None, *, msg='**Experimental API**: may change or be removed without notice.', warn_runtime=True)[source]¶

Mark a function as experimental.

This signals to users that the decorated function is considered experimental and may change or be removed without notice.

Prepends a Sphinx .. warning:: directive to the function’s docstring and, when warn_runtime is True, emits an ExperimentalWarning at runtime each time the function is called.

Parameters:

obj (callable or None) – When used as a bare decorator (@experimental), obj is the decorated function. When used with arguments (@experimental(...)), obj is None and a decorator is returned.
msg (str, optional) – Text inserted into the Sphinx .. warning:: directive. If multi-line, each line should be plain unindented text.
warn_runtime (bool, optional) – If True (default), emit an ExperimentalWarning on each call. If False, only the docstring is modified and the original function is returned.

Notes

The Sphinx .. warning:: directive is only rendered by documentation tools that import and execute the decorator during the build process. This works with sphinx.ext.autodoc but not with Sphinx AutoAPI, which generates documentation from static code analysis without importing modules.

To silence runtime warnings, use any of Python’s standard mechanisms:

import warnings
from earthkit.utils.decorators.experimental import ExperimentalWarning
warnings.filterwarnings("ignore", category=ExperimentalWarning)

Or via the environment variable PYTHONWARNINGS:

export PYTHONWARNINGS="ignore:earthkit experimental:"

Examples

>>> from earthkit.utils.decorators.experimental import experimental
>>> @experimental
... def compute():
...     return 42
...