diff --git a/altair/utils/__init__.py b/altair/utils/__init__.py index 97fd67f26..28650911e 100644 --- a/altair/utils/__init__.py +++ b/altair/utils/__init__.py @@ -11,7 +11,7 @@ ) from .html import spec_to_html from .plugin_registry import PluginRegistry -from .deprecation import AltairDeprecationWarning, deprecated +from .deprecation import AltairDeprecationWarning, deprecated, deprecated_warn from .schemapi import Undefined, Optional @@ -22,6 +22,7 @@ "SchemaBase", "Undefined", "deprecated", + "deprecated_warn", "display_traceback", "infer_encoding_types", "infer_vegalite_type", diff --git a/altair/utils/deprecation.py b/altair/utils/deprecation.py index 740920d35..88c12516c 100644 --- a/altair/utils/deprecation.py +++ b/altair/utils/deprecation.py @@ -1,6 +1,7 @@ from __future__ import annotations import sys +import warnings from typing import TYPE_CHECKING if sys.version_info >= (3, 13): @@ -70,3 +71,43 @@ def deprecated( """ msg = _format_message(version, alternative, message) return _deprecated(msg, category=category, stacklevel=stacklevel) + + +def deprecated_warn( + message: LiteralString, + *, + version: LiteralString, + alternative: LiteralString | None = None, + category: type[AltairDeprecationWarning] = AltairDeprecationWarning, + stacklevel: int = 2, +) -> None: + """Indicate that the current code path is deprecated. + + This should be used for non-trivial cases *only*. ``@deprecated`` should + always be preferred as it is recognized by static type checkers. + + Parameters + ---------- + message + Explanation of the deprecated behaviour. + + .. note:: + Unlike ``@deprecated``, this is *not* optional. + + version + ``altair`` version the deprecation first appeared. + alternative + Suggested replacement argument/method/function. + category + The runtime warning type emitted. + stacklevel + How far up the call stack to make this warning appear. + A value of ``2`` attributes the warning to the caller + of the code calling ``deprecated_warn()``. + + References + ---------- + [warnings.warn](https://docs.python.org/3/library/warnings.html#warnings.warn) + """ + msg = _format_message(version, alternative, message) + warnings.warn(msg, category=category, stacklevel=stacklevel)