polars-runtime-compat 1.34.0b2__cp39-abi3-win_arm64.whl → 1.34.0b4__cp39-abi3-win_arm64.whl

polars/_utils/deprecation.py

@@ -1,406 +0,0 @@
-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",
-]