Module astrapy.utils.meta

def beta_method(method: Callable[P, R]) -> Callable[P, R]:
    @wraps(method)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        beta_warning_message = BETA_WARNING_TEMPLATE.format(
            method_name=method.__qualname__
        )
        warnings.warn(
            beta_warning_message,
            BetaFeatureWarning,
            stacklevel=2,
        )
        return method(*args, **kwargs)

    return wrapper

def check_deprecated_alias(
    new_name: str | None,
    deprecated_name: str | None,
) -> str | None:
    """Generic blueprint utility for deprecating parameters through an alias.

    Normalize the two aliased parameter names, raising deprecation
    when needed and an error if both parameter supplied.
    The returned value is the final one for the parameter.
    """

    if deprecated_name is None:
        # no need for deprecation nor exceptions
        return new_name
    else:
        # issue a deprecation warning
        the_warning = DeprecatedWarning(
            "Parameter 'deprecated_name'",
            deprecated_in="2.0.0",
            removed_in="3.0.0",
            details="Please use 'new_name' instead.",
        )
        warnings.warn(
            the_warning,
            stacklevel=3,
        )

        if new_name is None:
            return deprecated_name
        else:
            msg = (
                "Parameters `new_name` and `deprecated_name` "
                "(a deprecated alias for the former) cannot be passed at the same time."
            )
            raise ValueError(msg)

def deprecated_property(
    new_name: str, deprecated_in: str, removed_in: str
) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """
    Decorator for a @property that is a deprecated alias for attribute 'new_name'.
    """

    def _deprecator(method: Callable[P, R]) -> Callable[P, R]:
        @wraps(method)
        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
            the_warning = DeprecatedWarning(
                f"Property '{method.__name__}'",
                deprecated_in=deprecated_in,
                removed_in=removed_in,
                details=f"Please use '{new_name}' instead.",
            )
            warnings.warn(
                the_warning,
                stacklevel=2,
            )
            return method(*args, **kwargs)

        return wrapper

    return _deprecator

def issue_plain_warning(message: str, stacklevel: int = 2) -> None:
    warnings.warn(
        message,
        stacklevel=stacklevel,
    )

class BetaFeatureWarning(UserWarning):
    pass