def annotate()

in lib/src/klio/transforms/_utils.py [0:0]
31 lines of code
6 McCabe index (conditional complexity)

def annotate(state, since=None, current=None, message=None):
    """Decorates an API with a `deprecated` or `experimental` annotation.

    When a user uses a objected decorated with this annotation, they
    will see a `KlioFutureWarning` or `KlioDeprecationWarning` during
    runtime.

    Args:
        state (AnnotatedStates): the kind of annotation (AnnotatedStates.
            DEPRECATED or AnnotatedStates.EXPERIMENTAL).
        since: the version that causes the annotation (used for
            AnnotatedStates.DEPRECATED when no `message` is given;
            ignored for AnnotatedStates.EXPERIMENTAL).
        current: the suggested replacement function.
        message: if the default message does not suffice, the message
            can be changed using this argument. Default message for

    Returns:
        The decorator for the API.
    """

    def wrapper(func):
        @functools.wraps(func)
        def inner(*args, **kwargs):
            warning_type = KlioFutureWarning
            if state == AnnotatedStates.DEPRECATED:
                warning_type = KlioDeprecationWarning

            warn_message = message
            if message is None:
                addl_ctx = (
                    " and is subject to incompatible changes, or removal "
                    "in a future release of Klio."
                )
                if state == AnnotatedStates.DEPRECATED:
                    _since = " since {}".format(since) if since else ""
                    _current = (
                        ". Use {} instead".format(current) if current else ""
                    )
                    addl_ctx = "{}{}.".format(_since, _current)

                msg_kwargs = {
                    "obj": func.__name__,
                    "annotation": state.value,
                    "addl_ctx": addl_ctx,
                }
                warn_message = "'{obj}' is {annotation}{addl_ctx}".format(
                    **msg_kwargs
                )

            warnings.warn(warn_message, warning_type, stacklevel=2)
            return func(*args, **kwargs)

        return inner

    return wrapper