neuralqx.utils.deprecation module

This file contains logic for different decorators responsible for different deprecation warnings

NOTE: part(s) of, or the entire content, of this file is obtained from NetKet’s source code

the original copyright mentioned above applies.

deprecated(reason=None, func_name=None)

Decorator to mark a function or class as deprecated.

When applied, calling the decorated object will emit a FutureWarning indicating that the function/class is deprecated and will be removed in a future release. An optional reason can be included to provide migration notes, and an optional func_name can be supplied to override the name shown in the warning (useful for aliases).

Parameters:

  • reason (str) – Optional additional notes describing why the object is deprecated and/or how to migrate away from it.

  • func_name (str) – Optional name to display in the warning instead of func.__name__.

Returns:

A decorator that wraps the target callable/class and emits a deprecation warning on use.

deprecation_warning(depr_message)

Emit a FutureWarning with a provided deprecation message.

The message is passed through textwrap.dedent() and emitted with stacklevel=2 so the warning points to the user’s call site.

Parameters:

depr_message (str) – Message describing the deprecation and (optionally) the recommended replacement.

Return type:

None

Returns:

None.

old_name_deprecation(function_name, reason='')

Decorator factory to deprecate an old function name in favour of a new one.

When applied, calling the decorated function emits a FutureWarning informing the user that func.__name__ has been renamed to function_name and that the old name will be removed in a future release. An optional reason may be appended with additional context.

Parameters:

  • function_name (str) – The new (preferred) function name to which users should migrate.

  • reason (str) – Optional additional notes describing the rename and/or migration guidance.

Returns:

A decorator that wraps the function and emits a rename deprecation warning on call.

parameter_name_deprecation(old_param, new_param, reason='')

Decorator factory to deprecate a keyword parameter name in favour of a new one.

When applied, calling the decorated function will emit a FutureWarning if the user supplies old_param as a keyword argument, indicating that it will be renamed to new_param in a future release. The function call proceeds unchanged (the keyword is not automatically renamed).

Parameters:

  • old_param (str) – Deprecated keyword parameter name.

  • new_param (str) – Replacement keyword parameter name that users should switch to.

  • reason (str) – Optional additional notes describing the change and/or migration guidance.

Returns:

A decorator that wraps the function and emits a parameter rename warning when old_param is used.

deprecated_class(reason=None, class_name=None, *, category=<class 'FutureWarning'>, warn_on_subclasses=False, stacklevel=2)

Decorator to mark a class as deprecated.

Unlike function-style deprecation decorators, this decorator preserves the class object (so isinstance, subclassing, and introspection continue to work) and emits a warning when the class is instantiated.

The warning is emitted from a wrapped __init__ method.

Parameters:

  • reason (str | None) – Optional additional migration notes (e.g. replacement class or API changes).

  • class_name (str | None) – Optional name to display in the warning instead of cls.__name__. Useful when deprecating an alias/shim class.

  • category (type[Warning]) – Warning category to emit. Defaults to FutureWarning.

  • warn_on_subclasses (bool) – If False (default), warn only when the deprecated class itself is instantiated. If True, also warn when subclasses (that inherit the wrapped __init__) are instantiated.

  • stacklevel (int) – Stacklevel passed to warnings.warn(). Default 2 is usually correct.

Return type:

Callable[[TypeVar(T, bound= type)], TypeVar(T, bound= type)]

Returns:

Callable[[type], type] A class decorator that wraps __init__ and returns the original class object.

Notes

  • This decorator modifies cls.__init__ in place.

  • It is safe for normal classes and dataclasses.

  • It is not intended for deprecating a plain alias assignment like OldClass = NewClass because aliases provide no call hook. For aliases, create a shim class and decorate that shim.

deprecated_module(module_name, reason='', *, stacklevel=2)
Return type:

None

deprecate_public_api(namespace, exports=None, *, module_name=None, reason=None, warn_on_module_import=False, internal_module_prefixes=(), module_warning_stacklevel=5)

Deprecates an entire public API namespace, typically a package or module __init__.

This utility wraps exported functions and classes with deprecation warnings. It can also optionally emit a module-level deprecation warning at import time.

Parameters:

  • namespace (MutableMapping[str, Any]) – Module globals dictionary, usually globals().

  • exports (Optional[Iterable[str]]) – Public names to deprecate. Defaults to namespace["__all__"].

  • module_name (str | None) – Fully qualified module name used in warning labels. Defaults to namespace["__name__"].

  • reason (Union[str, Callable[[str], str], None]) – Additional migration guidance. Can be either a static string or a callable that receives the fully qualified target name and returns a message.

  • warn_on_module_import (bool) – Whether to emit a module-level deprecation warning at import time.

  • internal_module_prefixes (tuple[str, ...]) – Optional module-name prefixes for internal call sites where class instantiation should not emit deprecation warnings.

  • module_warning_stacklevel (int) – Stack level used for module-level import warnings. Defaults to 5 so warnings typically point to the import call site rather than inside deprecation internals.

Return type:

None