From fe1917e3d4986dfa431f428146819622b83b6546 Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Mon, 1 Jul 2024 19:10:31 +0100
Subject: [PATCH] feat: adds `deprecate` function

This wrapper format seems to satisfy `pyright` enough to trigger a strikethrough
---
 altair/utils/deprecation.py | 42 +++++++++++++++++++++++++++++++++++++
 altair/vegalite/v5/api.py   |  2 +-
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/altair/utils/deprecation.py b/altair/utils/deprecation.py
index af6b3b657..17f412bb8 100644
--- a/altair/utils/deprecation.py
+++ b/altair/utils/deprecation.py
@@ -71,6 +71,48 @@ def __call__(self, arg: _T, /) -> _T:
         return super().__call__(arg)
 
 
+# NOTE: Annotating the return type breaks `pyright` detecting [reportDeprecated]
+def deprecate(
+    *,
+    version: te.LiteralString,
+    alternative: te.LiteralString | None = None,
+    message: te.LiteralString | None = None,
+    category: type[AltairDeprecationWarning] | None = AltairDeprecationWarning,
+    stacklevel: int = 1,
+):
+    """Indicate that a class, function or overload is deprecated.
+
+    When this decorator is applied to an object, the type checker
+    will generate a diagnostic on usage of the deprecated object.
+
+    Parameters
+    ----------
+    version
+        ``altair`` version the deprecation first appeared.
+    alternative
+        Suggested replacement class/method/function.
+    message
+        Additional message appended to ``version``, ``alternative``.
+    category
+        If the *category* is ``None``, no warning is emitted at runtime.
+    stacklevel
+        The *stacklevel* determines where the
+        warning is emitted. If it is ``1`` (the default), the warning
+        is emitted at the direct caller of the deprecated object; if it
+        is higher, it is emitted further up the stack.
+        Static type checker behavior is not affected by the *category*
+        and *stacklevel* arguments.
+    """
+    output = f"Deprecated in `altair={version}`."
+    if alternative:
+        output = f"{output} Use {alternative} instead."
+    return te.deprecated(
+        f"{output}\n\n{message}" if message else output,
+        category=category,
+        stacklevel=stacklevel,
+    )
+
+
 def msg(
     *,
     version: te.LiteralString,
diff --git a/altair/vegalite/v5/api.py b/altair/vegalite/v5/api.py
index e82271941..7c0d2ac76 100644
--- a/altair/vegalite/v5/api.py
+++ b/altair/vegalite/v5/api.py
@@ -799,7 +799,7 @@ def selection_multi(**kwargs):
     return _selection(type="point", **kwargs)
 
 
-@utils.deprecation.deprecated("", version="5.0.0", alternative="selection_point")
+@utils.deprecation.deprecate(version="5.0.0", alternative="selection_point")
 def selection_single(**kwargs):
     """'selection_single' is deprecated.  Use 'selection_point'"""
     return _selection(type="point", **kwargs)