Spaces:
Running
Running
| from __future__ import annotations | |
| import sys | |
| import warnings | |
| from typing import TYPE_CHECKING | |
| if sys.version_info >= (3, 13): | |
| from warnings import deprecated as _deprecated | |
| else: | |
| from typing_extensions import deprecated as _deprecated | |
| if TYPE_CHECKING: | |
| if sys.version_info >= (3, 11): | |
| from typing import LiteralString | |
| else: | |
| from typing_extensions import LiteralString | |
| class AltairDeprecationWarning(DeprecationWarning): ... | |
| def _format_message( | |
| version: LiteralString, | |
| alternative: LiteralString | None, | |
| message: LiteralString | None, | |
| /, | |
| ) -> LiteralString: | |
| output = f"Deprecated in `altair={version}`." | |
| if alternative: | |
| output = f"{output} Use {alternative} instead." | |
| return f"{output}\n{message}" if message else output | |
| # NOTE: Annotating the return type breaks `pyright` detecting [reportDeprecated] | |
| # NOTE: `LiteralString` requirement is introduced by stubs | |
| def deprecated( | |
| *, | |
| version: LiteralString, | |
| alternative: LiteralString | None = None, | |
| message: LiteralString | None = None, | |
| category: type[AltairDeprecationWarning] | None = AltairDeprecationWarning, | |
| stacklevel: int = 1, | |
| ): # te.deprecated | |
| """ | |
| 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. | |
| References | |
| ---------- | |
| [PEP 702](https://peps.python.org/pep-0702/) | |
| """ | |
| 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) | |