Implementation:Huggingface Datasets Deprecated Decorator

Knowledge Sources	Huggingface Datasets HF Datasets Docs
Domains	API_Management, Utilities
Last Updated	2026-02-14 18:00 GMT

Overview

Deprecation utilities providing the @deprecated decorator and DeprecatedEnum base class.

Description

This module provides two mechanisms for deprecating public API surface in the HuggingFace Datasets library:

1. The @deprecated decorator factory: A decorator that can be applied to both functions and classes. When a deprecated function or class is used, it emits a FutureWarning with a configurable help message. The warning is emitted only once per decorated function (tracked via a module-level set of function hashes), preventing log spam during repeated usage. When applied to a class, the decorator wraps the class's __init__ method so that the warning fires on instantiation rather than on class definition.

2. The DeprecatedEnum base class: An Enum class that uses a custom metaclass (OnAccess) to trigger deprecation warnings whenever any enum member is accessed -- whether via attribute access (MyEnum.MEMBER), item access (MyEnum["MEMBER"]), or value instantiation (MyEnum("value")). Each enum member has a deprecate method that emits a FutureWarning. Subclasses can override the help_message property to provide migration guidance.

Usage

Use @deprecated to mark functions or classes that will be removed in the next major version. Use DeprecatedEnum as a base class for enum types that should trigger deprecation warnings on member access.

Code Reference

Source Location

• Repository: datasets
• File: src/datasets/utils/deprecation_utils.py
• Lines: 1-105

Signature

def deprecated(help_message: Optional[str] = None):
    """Decorator to mark a class or a function as deprecated.

    Args:
        help_message (str, optional): An optional message to guide the user on
            how to switch to non-deprecated usage of the library.
    """

class OnAccess(enum.EnumMeta):
    """Enum metaclass that calls a user-specified function whenever a member is accessed."""
    def __getattribute__(cls, name):
    def __getitem__(cls, name):
    def __call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1):

class DeprecatedEnum(enum.Enum, metaclass=OnAccess):
    """Enum class that calls `deprecate` method whenever a member is accessed."""
    def __new__(cls, value):
    @property
    def help_message(self):
    def deprecate(self):

Import

from datasets.utils.deprecation_utils import deprecated, DeprecatedEnum

I/O Contract

deprecated() Decorator

Name	Type	Required	Description
help_message	Optional[str]	No	An optional message appended to the deprecation warning, guiding users to the replacement API.

Behavior:

• When applied to a function: wraps the function to emit a FutureWarning on first call, then delegates to the original function.
• When applied to a class: wraps the class's __init__ method to emit the warning on first instantiation, and returns the class unchanged.
• Warnings are deduplicated: each decorated function/class triggers its warning only once per process.

DeprecatedEnum Base Class

Method/Property	Description
__new__(cls, value)	Creates new enum members and binds the deprecate method as the _on_access callback.
help_message (property)	Returns an empty string by default. Subclasses should override this to provide migration guidance.
deprecate(self)	Emits a FutureWarning indicating the enum class is deprecated.

OnAccess Metaclass

Method	Trigger	Description
__getattribute__	MyEnum.MEMBER	Calls _on_access() on attribute-style member access.
__getitem__	MyEnum["MEMBER"]	Calls _on_access() on item-style member access.
__call__	MyEnum("value")	Calls _on_access() on value-based member lookup.

Usage Examples

Deprecating a Function

from datasets.utils.deprecation_utils import deprecated

@deprecated("Use `new_function()` instead.")
def old_function(x, y):
    return x + y

# First call emits: FutureWarning: old_function is deprecated and will be
# removed in the next major version of datasets. Use `new_function()` instead.
result = old_function(1, 2)

# Subsequent calls do not repeat the warning
result = old_function(3, 4)

Deprecating a Class

from datasets.utils.deprecation_utils import deprecated

@deprecated("Use `NewBuilder` instead.")
class OldBuilder:
    def __init__(self, name):
        self.name = name

# Warning is emitted on first instantiation
obj = OldBuilder("test")

Creating a Deprecated Enum

from datasets.utils.deprecation_utils import DeprecatedEnum

class OldMode(DeprecatedEnum):
    MODE_A = "mode_a"
    MODE_B = "mode_b"

    @property
    def help_message(self):
        return "Use `NewMode` instead."

# Accessing any member triggers a FutureWarning
mode = OldMode.MODE_A

Related Pages

Implements Principle

• Principle:Huggingface_Datasets_Deprecation_Management