docs(typing): Adds static-only deprecation for themes.register

#3618 (comment)

altair/__init__.py

@@ -652,7 +652,6 @@ def __dir__():
 from altair.expr import expr
 from altair.utils import AltairDeprecationWarning, parse_shorthand, Undefined
 from altair import typing, theme
-from typing import Any as _Any
 
 
 def load_ipython_extension(ipython):
@@ -661,7 +660,7 @@ def load_ipython_extension(ipython):
     ipython.register_magic_function(vegalite, "cell")
 
 
-def __getattr__(name: str) -> _Any:
+def __getattr__(name: str):
     from altair.utils.deprecation import deprecated_warn
 
     if name == "themes":

altair/theme.py

@@ -242,7 +242,7 @@ def custom_theme() -> theme.ThemeConfig:
     # HACK: See for `LiteralString` requirement in `name`
     # https://github.com/vega/altair/pull/3526#discussion_r1743350127
     def decorate(func: Plugin[ThemeConfig], /) -> Plugin[ThemeConfig]:
-        _themes.register(name, func)
+        _register(name, func)
         if enable:
             _themes.enable(name)
 
@@ -269,7 +269,7 @@ def unregister(name: LiteralString) -> Plugin[ThemeConfig]:
     TypeError
         When ``name`` has not been registered.
     """
-    plugin = _themes.register(name, None)
+    plugin = _register(name, None)
     if plugin is None:
         msg = (
             f"Found no theme named {name!r} in registry.\n"
@@ -306,3 +306,16 @@ def __getattr__(name: str) -> Any:
     else:
         msg = f"module {__name__!r} has no attribute {name!r}"
         raise AttributeError(msg)
+
+
+def _register(
+    name: LiteralString, fn: Plugin[ThemeConfig] | None, /
+) -> Plugin[ThemeConfig] | None:
+    if fn is None:
+        return _themes._plugins.pop(name, None)
+    elif _themes.plugin_type(fn):
+        _themes._plugins[name] = fn
+        return fn
+    else:
+        msg = f"{type(fn).__name__!r} is not a callable theme\n\n{fn!r}"
+        raise TypeError(msg)

altair/utils/deprecation.py

@@ -17,7 +17,12 @@
     else:
         from typing_extensions import LiteralString
 
-__all__ = ["AltairDeprecationWarning", "deprecated", "deprecated_warn"]
+__all__ = [
+    "AltairDeprecationWarning",
+    "deprecated",
+    "deprecated_static_only",
+    "deprecated_warn",
+]
 
 
 class AltairDeprecationWarning(DeprecationWarning): ...
@@ -124,6 +129,30 @@ def deprecated_warn(
         raise NotImplementedError(action)
 
 
+deprecated_static_only = _deprecated
+"""
+Using this decorator **exactly as described**, ensures the message is displayed to a static type checker.
+
+**BE CAREFUL USING THIS**.
+
+See screenshots in `comment`_ for motivation.
+
+Every use should look like::
+
+    @deprecated_static_only(
+        "Deprecated in `altair=5.5.0`. Use altair.other instead.",
+        category=None,
+    )
+    def old_function(*args): ...
+
+If a runtime warning is desired, use `@alt.utils.deprecated` instead.
+
+.. _comment:
+    https://github.com/vega/altair/pull/3618#issuecomment-2423991968
+---
+"""
+
+
 class _WarningsMonitor:
     def __init__(self) -> None:
         self._warned: dict[LiteralString, Literal[True]] = {}

altair/vegalite/v5/theme.py

@@ -4,6 +4,7 @@
 
 from typing import TYPE_CHECKING, Any, Final, Literal, get_args
 
+from altair.utils.deprecation import deprecated_static_only
 from altair.utils.plugin_registry import Plugin, PluginRegistry
 from altair.vegalite.v5.schema._config import ThemeConfig
 from altair.vegalite.v5.schema._typing import VegaThemes
@@ -69,6 +70,15 @@ def names(self) -> list[str]:
         """Return the names of the registered and entry points themes."""
         return super().names()
 
+    @deprecated_static_only(
+        "Deprecated in `altair=5.5.0`. Use @altair.theme.register instead.",
+        category=None,
+    )
+    def register(
+        self, name: str, value: Plugin[ThemeConfig] | None
+    ) -> Plugin[ThemeConfig] | None:
+        return super().register(name, value)
+
 
 class VegaTheme:
     """Implementation of a builtin vega theme."""