|
|
import enum |
|
|
import inspect |
|
|
import warnings |
|
|
from functools import wraps |
|
|
from typing import Callable, Optional |
|
|
|
|
|
from .logging import get_logger |
|
|
|
|
|
|
|
|
_emitted_deprecation_warnings = set() |
|
|
logger = get_logger(__name__) |
|
|
|
|
|
|
|
|
def deprecated(help_message: Optional[str] = None): |
|
|
"""Decorator to mark a class or a function as deprecated. |
|
|
|
|
|
Args: |
|
|
help_message (:obj:`str`, optional): An optional message to guide the user on how to |
|
|
switch to non-deprecated usage of the library. |
|
|
""" |
|
|
|
|
|
def decorator(deprecated_class_or_function: Callable): |
|
|
global _emitted_deprecation_warnings |
|
|
|
|
|
if inspect.isclass(deprecated_class_or_function): |
|
|
deprecated_function = deprecated_class_or_function.__init__ |
|
|
name = deprecated_class_or_function.__name__ |
|
|
else: |
|
|
deprecated_function = deprecated_class_or_function |
|
|
name = deprecated_function.__name__ |
|
|
|
|
|
name = name if name != "__init__" else deprecated_function.__qualname__.split(".")[-2] |
|
|
|
|
|
warning_msg = ( |
|
|
f"{name} is deprecated and will be removed in the next major version of datasets." + f" {help_message}" |
|
|
if help_message |
|
|
else "" |
|
|
) |
|
|
|
|
|
@wraps(deprecated_function) |
|
|
def wrapper(*args, **kwargs): |
|
|
func_hash = hash(deprecated_function) |
|
|
if func_hash not in _emitted_deprecation_warnings: |
|
|
warnings.warn(warning_msg, category=FutureWarning, stacklevel=2) |
|
|
_emitted_deprecation_warnings.add(func_hash) |
|
|
return deprecated_function(*args, **kwargs) |
|
|
|
|
|
wrapper._decorator_name_ = "deprecated" |
|
|
|
|
|
if inspect.isclass(deprecated_class_or_function): |
|
|
deprecated_class_or_function.__init__ = wrapper |
|
|
return deprecated_class_or_function |
|
|
else: |
|
|
return wrapper |
|
|
|
|
|
return decorator |
|
|
|
|
|
|
|
|
class OnAccess(enum.EnumMeta): |
|
|
""" |
|
|
Enum metaclass that calls a user-specified function whenever a member is accessed. |
|
|
""" |
|
|
|
|
|
def __getattribute__(cls, name): |
|
|
obj = super().__getattribute__(name) |
|
|
if isinstance(obj, enum.Enum) and obj._on_access: |
|
|
obj._on_access() |
|
|
return obj |
|
|
|
|
|
def __getitem__(cls, name): |
|
|
member = super().__getitem__(name) |
|
|
if member._on_access: |
|
|
member._on_access() |
|
|
return member |
|
|
|
|
|
def __call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1): |
|
|
obj = super().__call__(value, names, module=module, qualname=qualname, type=type, start=start) |
|
|
if isinstance(obj, enum.Enum) and obj._on_access: |
|
|
obj._on_access() |
|
|
return obj |
|
|
|
|
|
|
|
|
class DeprecatedEnum(enum.Enum, metaclass=OnAccess): |
|
|
""" |
|
|
Enum class that calls `deprecate` method whenever a member is accessed. |
|
|
""" |
|
|
|
|
|
def __new__(cls, value): |
|
|
member = object.__new__(cls) |
|
|
member._value_ = value |
|
|
member._on_access = member.deprecate |
|
|
return member |
|
|
|
|
|
@property |
|
|
def help_message(self): |
|
|
return "" |
|
|
|
|
|
def deprecate(self): |
|
|
help_message = f" {self.help_message}" if self.help_message else "" |
|
|
warnings.warn( |
|
|
f"'{self.__objclass__.__name__}' is deprecated and will be removed in the next major version of datasets." |
|
|
+ help_message, |
|
|
FutureWarning, |
|
|
stacklevel=3, |
|
|
) |
|
|
|
