81 lines
2.3 KiB
Python
81 lines
2.3 KiB
Python
"""Helper functions for deprecation.
|
|
|
|
This interface is itself unstable and may change without warning. Do
|
|
not use these functions yourself, even as a joke. The underscores are
|
|
there for a reason. No support will be given.
|
|
|
|
In particular, most of this will go away without warning once
|
|
Beautiful Soup drops support for Python 3.11, since Python 3.12
|
|
defines a `@typing.deprecated()
|
|
decorator. <https://peps.python.org/pep-0702/>`_
|
|
"""
|
|
|
|
import functools
|
|
import warnings
|
|
|
|
from typing import (
|
|
Any,
|
|
Callable,
|
|
)
|
|
|
|
|
|
def _deprecated_alias(old_name: str, new_name: str, version: str):
|
|
"""Alias one attribute name to another for backward compatibility
|
|
|
|
:meta private:
|
|
"""
|
|
|
|
@property
|
|
def alias(self) -> Any:
|
|
":meta private:"
|
|
warnings.warn(
|
|
f"Access to deprecated property {old_name}. (Replaced by {new_name}) -- Deprecated since version {version}.",
|
|
DeprecationWarning,
|
|
stacklevel=2,
|
|
)
|
|
return getattr(self, new_name)
|
|
|
|
@alias.setter
|
|
def alias(self, value: str) -> None:
|
|
":meta private:"
|
|
warnings.warn(
|
|
f"Write to deprecated property {old_name}. (Replaced by {new_name}) -- Deprecated since version {version}.",
|
|
DeprecationWarning,
|
|
stacklevel=2,
|
|
)
|
|
return setattr(self, new_name, value)
|
|
|
|
return alias
|
|
|
|
|
|
def _deprecated_function_alias(
|
|
old_name: str, new_name: str, version: str
|
|
) -> Callable[[Any], Any]:
|
|
def alias(self, *args: Any, **kwargs: Any) -> Any:
|
|
":meta private:"
|
|
warnings.warn(
|
|
f"Call to deprecated method {old_name}. (Replaced by {new_name}) -- Deprecated since version {version}.",
|
|
DeprecationWarning,
|
|
stacklevel=2,
|
|
)
|
|
return getattr(self, new_name)(*args, **kwargs)
|
|
|
|
return alias
|
|
|
|
|
|
def _deprecated(replaced_by: str, version: str) -> Callable:
|
|
def deprecate(func: Callable) -> Callable:
|
|
@functools.wraps(func)
|
|
def with_warning(*args: Any, **kwargs: Any) -> Any:
|
|
":meta private:"
|
|
warnings.warn(
|
|
f"Call to deprecated method {func.__name__}. (Replaced by {replaced_by}) -- Deprecated since version {version}.",
|
|
DeprecationWarning,
|
|
stacklevel=2,
|
|
)
|
|
return func(*args, **kwargs)
|
|
|
|
return with_warning
|
|
|
|
return deprecate
|