From 08f540849d4c86672c822d93a5a114cb266cbfa8 Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Wed, 3 Jul 2024 19:06:52 +0100
Subject: [PATCH] feat: adds `deprecated_warn`

Non-decorator counterpart to `@deprecated`
---
 altair/utils/__init__.py    |  3 ++-
 altair/utils/deprecation.py | 41 +++++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)

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)