polars-runtime-compat 1.34.0b2__cp39-abi3-macosx_10_12_x86_64.whl

polars/_utils/deprecation.py

@@ -0,0 +1,406 @@
+from __future__ import annotations
+
+import ast
+import inspect
+import sys
+from collections import defaultdict
+from collections.abc import Sequence
+from functools import wraps
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, TypeVar, get_args
+
+from polars._typing import DeprecationType
+
+if sys.version_info >= (3, 13):
+    from warnings import deprecated
+else:
+    try:
+        from typing_extensions import deprecated
+    except ImportError:
+
+        def deprecated(  # type: ignore[no-redef]
+            message: str,
+        ) -> Callable[[Callable[P, T]], Callable[P, T]]:
+            return _deprecate_function(message)
+
+
+from polars._utils.various import issue_warning
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    if sys.version_info >= (3, 10):
+        from typing import ParamSpec
+    else:
+        from typing_extensions import ParamSpec
+    from polars._typing import Ambiguous
+
+    P = ParamSpec("P")
+    T = TypeVar("T")
+
+USE_EARLIEST_TO_AMBIGUOUS: Mapping[bool, Ambiguous] = {
+    True: "earliest",
+    False: "latest",
+}
+
+
+def issue_deprecation_warning(message: str, *, version: str = "") -> None:
+    """
+    Issue a deprecation warning.
+
+    Parameters
+    ----------
+    message
+        The message associated with the warning.
+    version
+        The version in which deprecation occurred
+        (if the version number was not already included in `message`).
+    """
+    if version:
+        message = f"{message.strip()}\n(Deprecated in version {version})"
+    issue_warning(message, DeprecationWarning)
+
+
+def _deprecate_function(message: str) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator to mark a function as deprecated."""
+
+    def decorate(function: Callable[P, T]) -> Callable[P, T]:
+        @wraps(function)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            issue_deprecation_warning(message)
+            return function(*args, **kwargs)
+
+        wrapper.__signature__ = inspect.signature(function)  # type: ignore[attr-defined]
+        wrapper.__deprecated__ = message  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate
+
+
+def deprecate_streaming_parameter() -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator to mark `streaming` argument as deprecated due to being renamed."""
+
+    def decorate(function: Callable[P, T]) -> Callable[P, T]:
+        @wraps(function)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            if "streaming" in kwargs:
+                issue_deprecation_warning(
+                    "the `streaming` parameter was deprecated in 1.25.0; use `engine` instead."
+                )
+                if kwargs["streaming"]:
+                    kwargs["engine"] = "streaming"
+                elif "engine" not in kwargs:
+                    kwargs["engine"] = "in-memory"
+
+                del kwargs["streaming"]
+
+            return function(*args, **kwargs)
+
+        wrapper.__signature__ = inspect.signature(function)  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate
+
+
+def deprecate_renamed_parameter(
+    old_name: str, new_name: str, *, version: str
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    Decorator to mark a function parameter as deprecated due to being renamed.
+
+    Use as follows:
+
+        @deprecate_renamed_parameter("old_name", new_name="new_name")
+        def myfunc(new_name): ...
+
+    Ensure that you also update the function docstring with a note about the
+    deprecation, specifically adding a `.. versionchanged:: 0.0.0` directive
+    that states which parameter was renamed to which new name and in which
+    version the rename happened.
+    """
+
+    def decorate(function: Callable[P, T]) -> Callable[P, T]:
+        @wraps(function)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            _rename_keyword_argument(
+                old_name, new_name, kwargs, function.__qualname__, version
+            )
+            return function(*args, **kwargs)
+
+        wrapper.__signature__ = inspect.signature(function)  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate
+
+
+def _rename_keyword_argument(
+    old_name: str,
+    new_name: str,
+    kwargs: dict[str, object],
+    func_name: str,
+    version: str,
+) -> None:
+    """Rename a keyword argument of a function."""
+    if old_name in kwargs:
+        if new_name in kwargs:
+            is_deprecated = (
+                f"was deprecated in version {version}" if version else "is deprecated"
+            )
+            msg = (
+                f"`{func_name!r}` received both `{old_name!r}` and `{new_name!r}` as arguments;"
+                f" `{old_name!r}` {is_deprecated}, use `{new_name!r}` instead"
+            )
+            raise TypeError(msg)
+
+        in_version = f" in version {version}" if version else ""
+        issue_deprecation_warning(
+            f"the argument `{old_name}` for `{func_name}` is deprecated. "
+            f"It was renamed to `{new_name}`{in_version}."
+        )
+        kwargs[new_name] = kwargs.pop(old_name)
+
+
+def deprecate_nonkeyword_arguments(
+    allowed_args: list[str] | None = None, message: str | None = None, *, version: str
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    Decorator for deprecating the use of non-keyword arguments in a function.
+
+    Use as follows:
+
+        @deprecate_nonkeyword_arguments(allowed_args=["self", "val"], version="1.0.0")
+        def myfunc(self, val: int = 0, other: int: = 0): ...
+
+    Ensure that you also update the function docstring with a note about the
+    deprecation, specifically adding a `.. versionchanged:: 0.0.0` directive
+    that states that we now expect keyword args and in which version this
+    update happened.
+
+    Parameters
+    ----------
+    allowed_args
+        The names of some first arguments of the decorated function that are allowed to
+        be given as positional arguments. Should include "self" when decorating class
+        methods. If set to None (default), equal to all arguments that do not have a
+        default value.
+    message
+        Optionally overwrite the default warning message.
+    version
+        The Polars version number in which the warning is first issued.
+    """
+
+    def decorate(function: Callable[P, T]) -> Callable[P, T]:
+        old_sig = inspect.signature(function)
+
+        if allowed_args is not None:
+            allow_args = allowed_args
+        else:
+            allow_args = [
+                p.name
+                for p in old_sig.parameters.values()
+                if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+                and p.default is p.empty
+            ]
+
+        new_params = [
+            p.replace(kind=p.KEYWORD_ONLY)
+            if (
+                p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+                and p.name not in allow_args
+            )
+            else p
+            for p in old_sig.parameters.values()
+        ]
+        new_params.sort(key=lambda p: p.kind)
+
+        new_sig = old_sig.replace(parameters=new_params)
+
+        num_allowed_args = len(allow_args)
+        if message is None:
+            msg_format = (
+                f"all arguments of {function.__qualname__}{{except_args}} will be keyword-only in the next breaking release."
+                " Use keyword arguments to silence this warning."
+            )
+            msg = msg_format.format(except_args=_format_argument_list(allow_args))
+        else:
+            msg = message
+
+        @wraps(function)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            if len(args) > num_allowed_args:
+                issue_deprecation_warning(msg, version=version)
+            return function(*args, **kwargs)
+
+        wrapper.__signature__ = new_sig  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate
+
+
+def _format_argument_list(allowed_args: list[str]) -> str:
+    """Format allowed arguments list for use in the warning message of `deprecate_nonkeyword_arguments`."""  # noqa: W505
+    if "self" in allowed_args:
+        allowed_args.remove("self")
+    if not allowed_args:
+        return ""
+    elif len(allowed_args) == 1:
+        return f" except for {allowed_args[0]!r}"
+    else:
+        last = allowed_args[-1]
+        args = ", ".join([f"{x!r}" for x in allowed_args[:-1]])
+        return f" except for {args} and {last!r}"
+
+
+def deprecate_parameter_as_multi_positional(
+    old_name: str,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    Decorator to mark a function argument as deprecated due to being made multi-positional.
+
+    Use as follows:
+
+        @deprecate_parameter_as_multi_positional("columns")
+        def myfunc(*columns): ...
+
+    Ensure that you also update the function docstring with a note about the
+    deprecation, specifically adding a `.. versionchanged:: 0.0.0` directive
+    that states that we now expect positional args and in which version this
+    update happened.
+    """  # noqa: W505
+
+    def decorate(function: Callable[P, T]) -> Callable[P, T]:
+        @wraps(function)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            try:
+                arg_value = kwargs.pop(old_name)
+            except KeyError:
+                return function(*args, **kwargs)
+
+            issue_deprecation_warning(
+                f"passing `{old_name}` as a keyword argument is deprecated."
+                " Pass it as a positional argument instead."
+            )
+
+            if not isinstance(arg_value, Sequence) or isinstance(arg_value, str):
+                arg_value = (arg_value,)
+            elif not isinstance(arg_value, tuple):
+                arg_value = tuple(arg_value)
+
+            args = args + arg_value  # type: ignore[assignment]
+            return function(*args, **kwargs)
+
+        wrapper.__signature__ = inspect.signature(function)  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate
+
+
+def _find_deprecated_functions(
+    source: str, module_path: str
+) -> defaultdict[str, list[str]]:
+    tree = ast.parse(source)
+    object_path: list[str] = []
+
+    def deprecated(decorator: Any) -> str:
+        if isinstance(decorator, ast.Name):
+            return decorator.id if "deprecate" in decorator.id else ""
+        elif isinstance(decorator, ast.Call):
+            return deprecated(decorator.func)
+        return ""
+
+    def qualified_name(func_name: str) -> str:
+        return ".".join([module_path, *object_path, func_name])
+
+    results = defaultdict(list)
+
+    class FunctionVisitor(ast.NodeVisitor):
+        def visit_ClassDef(self, node: Any) -> None:
+            object_path.append(node.name)
+            self.generic_visit(node)
+            object_path.pop()
+
+        def visit_FunctionDef(self, node: Any) -> None:
+            if any((decorator_name := deprecated(d)) for d in node.decorator_list):
+                key = decorator_name.removeprefix("deprecate_").replace(
+                    "deprecated", "function"
+                )
+                results[key].append(qualified_name(node.name))
+            self.generic_visit(node)
+
+        visit_AsyncFunctionDef = visit_FunctionDef
+
+    FunctionVisitor().visit(tree)
+    return results
+
+
+def identify_deprecations(*types: DeprecationType) -> dict[str, list[str]]:
+    """
+    Return a dict identifying functions/methods that are deprecated in some way.
+
+    Parameters
+    ----------
+    *types
+        The types of deprecations to identify.
+        If empty, all types are returned; recognised values are:
+            - "function"
+            - "renamed_parameter"
+            - "streaming_parameter"
+            - "nonkeyword_arguments"
+            - "parameter_as_multi_positional"
+
+    Examples
+    --------
+    >>> from polars._utils.deprecation import identify_deprecations
+    >>> identify_deprecations("streaming_parameter")  # doctest: +IGNORE_RESULT
+    {'streaming_parameter': [
+        'functions.lazy.collect_all',
+        'functions.lazy.collect_all_async',
+        'lazyframe.frame.LazyFrame.collect',
+        'lazyframe.frame.LazyFrame.collect_async',
+        'lazyframe.frame.LazyFrame.explain',
+        'lazyframe.frame.LazyFrame.show_graph',
+    ]}
+    """
+    valid_types = set(get_args(DeprecationType))
+    for tp in types:
+        if tp not in valid_types:
+            msg = (
+                f"unrecognised deprecation type {tp!r}.\n"
+                f"Expected one (or more) of {repr(sorted(valid_types))[1:-1]}"
+            )
+            raise ValueError(msg)
+
+    package_path = Path(sys.modules["polars"].__file__).parent  # type: ignore[arg-type]
+    results = defaultdict(list)
+
+    for py_file in package_path.rglob("*.py"):
+        rel_path = py_file.relative_to(package_path)
+        module_path = ".".join(rel_path.parts).removesuffix(".py")
+        with py_file.open("r", encoding="utf-8") as src:
+            for deprecation_type, func_names in _find_deprecated_functions(
+                source=src.read(),
+                module_path=module_path,
+            ).items():
+                if deprecation_type not in valid_types:
+                    # note: raising here implies we have a new deprecation function
+                    # that should be added to the DeprecationType type alias
+                    msg = f"unrecognised deprecation type {tp!r}.\n"
+                    raise ValueError(msg)
+
+                results[deprecation_type].extend(func_names)
+
+    return {
+        dep: sorted(results[dep])
+        for dep in sorted(results)
+        if not types or dep in types
+    }
+
+
+__all__ = [
+    "deprecate_nonkeyword_arguments",
+    "deprecate_parameter_as_multi_positional",
+    "deprecate_renamed_parameter",
+    "deprecate_streaming_parameter",
+    "deprecated",
+    "identify_deprecations",
+]