trulens.core.utils.deprecation¶

trulens.core.utils.deprecation ¶

Utilities for handling deprecation.

Functions¶

module_getattr_override ¶

module_getattr_override(
    module: Optional[str] = None,
    message: Optional[str] = None,
)

Override module's __getattr__ to issue a deprecation errors when looking up attributes.

This expects deprecated names to be prefixed with DEP_ followed by their original pre-deprecation name.

Example

Before deprecationAfter deprecation

# issue module import warning:
package_dep_warn()

# define temporary implementations of to-be-deprecated attributes:
something = ... actual working implementation or alias

# define deprecated attribute with None/any value but name with "DEP_"
# prefix:
DEP_something = None

# issue module deprecation warning and override __getattr__ to issue
# deprecation errors for the above:
module_getattr_override()

Also issues a deprecation warning for the module itself. This will be used in the next deprecation stage for throwing errors after deprecation errors.

deprecated_str ¶

deprecated_str(s: str, reason: str)

Decorator for deprecated string literals.

is_deprecated ¶

is_deprecated(obj: Any)

Check if object is deprecated.

Presently only supports values created by deprecated_str.

deprecated_property ¶

deprecated_property(message: str)

Decorator for deprecated attributes defined as properties.

handle_deprecated_kwarg ¶

handle_deprecated_kwarg(
    kwargs: Dict[str, Any],
    old_name: str,
    new_name: str,
    new_value: Optional[str],
    stacklevel: int = 3,
) -> Optional[str]

Handle deprecated keyword argument that has been renamed.

This helper checks if an old parameter name is in kwargs, emits a deprecation warning, and returns the appropriate value to use.

PARAMETER	DESCRIPTION
`kwargs`	The kwargs dictionary to check and modify. The old key will be removed from this dictionary if present. TYPE: `Dict[str, Any]`
`old_name`	The deprecated parameter name. TYPE: `str`
`new_name`	The new parameter name. TYPE: `str`
`new_value`	The current value of the new parameter. TYPE: `Optional[str]`
`stacklevel`	Stack level for the warning. Defaults to 3 (caller's caller). TYPE: `int` DEFAULT: `3`

RETURNS	DESCRIPTION
`Optional[str]`	The value to use for the new parameter. If new_value is None and the
`Optional[str]`	old parameter was provided, returns the old parameter's value.
`Optional[str]`	Otherwise returns new_value unchanged.

Example

def my_function(new_param: Optional[str] = None, **kwargs):
    new_param = handle_deprecated_kwarg(
        kwargs, "old_param", "new_param", new_param
    )

packages_dep_warn ¶

packages_dep_warn(
    module: Optional[str] = None,
    message: Optional[str] = None,
)

Issue a deprecation warning for a backwards-compatibility modules.

This is specifically for the trulens_eval -> trulens module renaming and reorganization. If message is given, that is included first in the deprecation warning.

has_deprecated ¶

has_deprecated(obj: Union[Callable, Type]) -> bool

Check if a function or class has been deprecated.

has_moved ¶

has_moved(obj: Union[Callable, Type]) -> bool

Check if a function or class has been moved.

staticmethod_renamed ¶

staticmethod_renamed(new_name: str)

Issue a warning upon static method call that has been renamed or moved.

Issues the warning only once.

method_renamed ¶

method_renamed(new_name: str)

Issue a warning upon method call that has been renamed or moved.

Issues the warning only once.

function_moved ¶

function_moved(func: Callable, old: str, new: str)

Issue a warning upon function call that has been moved to a new location.

Issues the warning only once. The given callable must have a name, so it cannot be a lambda.

class_moved ¶

class_moved(
    cls: Type,
    old_location: Optional[str] = None,
    new_location: Optional[str] = None,
)

Issue a warning upon class instantiation that has been moved to a new location.

Issues the warning only once.

moved ¶

moved(
    globals_dict: Dict[str, Any],
    old: Optional[str] = None,
    new: Optional[str] = None,
    names: Optional[Iterable[str]] = None,
)

Replace all classes or function in the given dictionary with ones that issue a deprecation warning upon initialization or invocation.

You can use this with module globals_dict=globals() and names=__all__ to deprecate all exposed module members.

PARAMETER	DESCRIPTION
`globals_dict`	The dictionary to update. See globals. TYPE: `Dict[str, Any]`
`old`	The old location of the classes. TYPE: `Optional[str]` DEFAULT: `None`
`new`	The new location of the classes. TYPE: `Optional[str]` DEFAULT: `None`
`names`	The names of the classes or functions to update. If None, all classes and functions are updated. TYPE: `Optional[Iterable[str]]` DEFAULT: `None`