refactor(python): Improve deprecation utils

py-polars/polars/dataframe/frame.py

@@ -86,7 +86,10 @@
 from polars.utils._parse_expr_input import parse_as_expression
 from polars.utils._wrap import wrap_expr, wrap_ldf, wrap_s
 from polars.utils.convert import _timedelta_to_pl_duration
-from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
+from polars.utils.deprecation import (
+    deprecate_renamed_parameter,
+    issue_deprecation_warning,
+)
 from polars.utils.various import (
     _prepare_row_count_args,
     _process_null_values,
@@ -3180,7 +3183,7 @@ def write_parquet(
                 file, compression, compression_level, statistics, row_group_size
             )
 
-    @deprecated_alias(connection_uri="connection")
+    @deprecate_renamed_parameter("connection_uri", "connection", version="0.18.9")
     def write_database(
         self,
         table_name: str,
@@ -5878,7 +5881,7 @@ def hstack(
         else:
             return self._from_pydf(self._df.hstack([s._s for s in columns]))
 
-    @deprecated_alias(df="other")
+    @deprecate_renamed_parameter("df", "other", version="0.18.8")
     def vstack(self, other: DataFrame, *, in_place: bool = False) -> Self:
         """
         Grow this DataFrame vertically by stacking a DataFrame to it.
@@ -8153,7 +8156,7 @@ def null_count(self) -> Self:
         """
         return self._from_pydf(self._df.null_count())
 
-    @deprecated_alias(frac="fraction")
+    @deprecate_renamed_parameter("frac", "fraction", version="0.17.0")
     def sample(
         self,
         n: int | None = None,

py-polars/polars/expr/datetime.py

@@ -9,7 +9,7 @@
 from polars.utils._parse_expr_input import parse_as_expression
 from polars.utils._wrap import wrap_expr
 from polars.utils.convert import _timedelta_to_pl_duration
-from polars.utils.deprecation import deprecated_alias
+from polars.utils.deprecation import deprecate_renamed_parameter
 
 if TYPE_CHECKING:
     from datetime import timedelta
@@ -445,7 +445,7 @@ def to_string(self, format: str) -> Expr:
         """
         return wrap_expr(self._pyexpr.dt_to_string(format))
 
-    @deprecated_alias(fmt="format")
+    @deprecate_renamed_parameter("fmt", "format", version="0.17.3")
     def strftime(self, format: str) -> Expr:
         """
         Convert a Date/Time/Datetime column into a Utf8 column with the given format.

py-polars/polars/expr/expr.py

@@ -51,8 +51,8 @@
 )
 from polars.utils.convert import _timedelta_to_pl_duration
 from polars.utils.deprecation import (
-    deprecated,
-    deprecated_alias,
+    deprecate_function,
+    deprecate_renamed_parameter,
     warn_closed_future_change,
 )
 from polars.utils.meta import threadpool_size
@@ -3363,7 +3363,7 @@ def cut(
             self._pyexpr.cut(breaks, labels, left_closed, include_breaks)
         )
 
-    @deprecated_alias(probs="q")
+    @deprecate_renamed_parameter("probs", "q", version="0.18.8")
     def qcut(
         self,
         q: list[float] | int,
@@ -7904,7 +7904,7 @@ def shuffle(self, seed: int | None = None, fixed_seed: bool = False) -> Self:
             seed = random.randint(0, 10000)
         return self._from_pyexpr(self._pyexpr.shuffle(seed, fixed_seed))
 
-    @deprecated_alias(frac="fraction")
+    @deprecate_renamed_parameter("frac", "fraction", version="0.17.0")
     def sample(
         self,
         n: int | None = None,
@@ -8565,7 +8565,7 @@ def shrink_dtype(self) -> Self:
         """
         return self._from_pyexpr(self._pyexpr.shrink_dtype())
 
-    @deprecated(
+    @deprecate_function(
         "This method now does nothing. It has been superseded by the"
         " `comm_subexpr_elim` setting on `LazyFrame.collect`, which automatically"
         " caches expressions that are equal.",

py-polars/polars/expr/list.py

@@ -7,7 +7,10 @@
 from polars import functions as F
 from polars.utils._parse_expr_input import parse_as_expression
 from polars.utils._wrap import wrap_expr
-from polars.utils.deprecation import deprecated_alias, redirect
+from polars.utils.deprecation import (
+    deprecate_renamed_methods,
+    deprecate_renamed_parameter,
+)
 
 if TYPE_CHECKING:
     from datetime import date, datetime, time
@@ -16,14 +19,19 @@
     from polars.type_aliases import IntoExpr, NullBehavior, ToStructStrategy
 
 
-@redirect(
+@deprecate_renamed_methods(
     {
         "difference": "set_difference",
         "symmetric_difference": "set_symmetric_difference",
         "intersection": "set_intersection",
         "union": "set_union",
     },
-    version="0.18.10",
+    versions={
+        "difference": "0.18.10",
+        "symmetric_difference": "0.18.10",
+        "intersection": "0.18.10",
+        "union": "0.18.10",
+    },
 )
 class ExprListNameSpace:
     """Namespace for list related expressions."""
@@ -777,7 +785,7 @@ def count_match(self, element: IntoExpr) -> Expr:
         element = parse_as_expression(element, str_as_lit=True)
         return wrap_expr(self._pyexpr.list_count_match(element))
 
-    @deprecated_alias(name_generator="fields")
+    @deprecate_renamed_parameter("name_generator", "fields", version="0.17.12")
     def to_struct(
         self,
         n_field_strategy: ToStructStrategy = "first_non_null",

py-polars/polars/expr/string.py

@@ -7,7 +7,10 @@
 from polars.exceptions import ChronoFormatWarning
 from polars.utils._parse_expr_input import parse_as_expression
 from polars.utils._wrap import wrap_expr
-from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
+from polars.utils.deprecation import (
+    deprecate_renamed_parameter,
+    issue_deprecation_warning,
+)
 from polars.utils.various import find_stacklevel
 
 if TYPE_CHECKING:
@@ -193,7 +196,8 @@ def to_time(
         _validate_format_argument(format)
         return wrap_expr(self._pyexpr.str_to_time(format, strict, cache))
 
-    @deprecated_alias(datatype="dtype", fmt="format")
+    @deprecate_renamed_parameter("datatype", "dtype", version="0.17.3")
+    @deprecate_renamed_parameter("fmt", "format", version="0.17.3")
     def strptime(
         self,
         dtype: PolarsTemporalType,

py-polars/polars/expr/whenthen.py

@@ -6,7 +6,10 @@
 from polars.expr.expr import Expr
 from polars.utils._parse_expr_input import parse_as_expression
 from polars.utils._wrap import wrap_expr
-from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
+from polars.utils.deprecation import (
+    deprecate_renamed_parameter,
+    issue_deprecation_warning,
+)
 
 if TYPE_CHECKING:
     from polars.polars import PyExpr
@@ -26,7 +29,7 @@ class When:
     def __init__(self, when: Any):
         self._when = when
 
-    @deprecated_alias(expr="statement")
+    @deprecate_renamed_parameter("expr", "statement", version="0.18.9")
     def then(self, statement: IntoExpr) -> Then:
         """
         Attach a statement to the corresponding condition.
@@ -63,7 +66,7 @@ def _from_pyexpr(cls, pyexpr: PyExpr) -> Expr:  # type: ignore[override]
     def _pyexpr(self) -> PyExpr:
         return self._then.otherwise(F.lit(None)._pyexpr)
 
-    @deprecated_alias(predicate="condition")
+    @deprecate_renamed_parameter("predicate", "condition", version="0.18.9")
     def when(self, condition: IntoExpr) -> ChainedWhen:
         """
         Add a condition to the `when-then-otherwise` expression.
@@ -78,7 +81,7 @@ def when(self, condition: IntoExpr) -> ChainedWhen:
         condition_pyexpr = parse_as_expression(condition)
         return ChainedWhen(self._then.when(condition_pyexpr))
 
-    @deprecated_alias(expr="statement")
+    @deprecate_renamed_parameter("expr", "statement", version="0.18.9")
     def otherwise(self, statement: IntoExpr) -> Expr:
         """
         Define a default for the `when-then-otherwise` expression.
@@ -109,7 +112,7 @@ class ChainedWhen(Expr):
     def __init__(self, chained_when: Any):
         self._chained_when = chained_when
 
-    @deprecated_alias(expr="statement")
+    @deprecate_renamed_parameter("expr", "statement", version="0.18.9")
     def then(self, statement: IntoExpr) -> ChainedThen:
         """
         Attach a statement to the corresponding condition.
@@ -146,7 +149,7 @@ def _from_pyexpr(cls, pyexpr: PyExpr) -> Expr:  # type: ignore[override]
     def _pyexpr(self) -> PyExpr:
         return self._chained_then.otherwise(F.lit(None)._pyexpr)
 
-    @deprecated_alias(predicate="condition")
+    @deprecate_renamed_parameter("predicate", "condition", version="0.18.9")
     def when(self, condition: IntoExpr) -> ChainedWhen:
         """
         Add another condition to the `when-then-otherwise` expression.
@@ -161,7 +164,7 @@ def when(self, condition: IntoExpr) -> ChainedWhen:
         condition_pyexpr = parse_as_expression(condition)
         return ChainedWhen(self._chained_then.when(condition_pyexpr))
 
-    @deprecated_alias(expr="statement")
+    @deprecate_renamed_parameter("expr", "statement", version="0.18.9")
     def otherwise(self, statement: IntoExpr) -> Expr:
         """
         Define a default for the `when-then-otherwise` expression.

py-polars/polars/functions/aggregation/vertical.py

@@ -4,7 +4,10 @@
 
 import polars._reexport as pl
 import polars.functions as F
-from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
+from polars.utils.deprecation import (
+    deprecate_renamed_parameter,
+    issue_deprecation_warning,
+)
 
 if TYPE_CHECKING:
     from polars import Expr, Series
@@ -23,7 +26,7 @@ def all(
     ...
 
 
-@deprecated_alias(columns="exprs")
+@deprecate_renamed_parameter("columns", "exprs", version="0.18.7")
 def all(
     exprs: IntoExpr | Iterable[IntoExpr] | None = None, *more_exprs: IntoExpr
 ) -> Expr | bool | None:
@@ -111,7 +114,7 @@ def any(exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr) -> Expr:
     ...
 
 
-@deprecated_alias(columns="exprs")
+@deprecate_renamed_parameter("columns", "exprs", version="0.18.7")
 def any(
     exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr
 ) -> Expr | bool | None:
@@ -370,7 +373,7 @@ def sum(exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr) -> Expr:
     ...
 
 
-@deprecated_alias(column="exprs")
+@deprecate_renamed_parameter("column", "exprs", version="0.18.7")
 def sum(
     exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr
 ) -> Expr | int | float:
@@ -466,7 +469,7 @@ def cumsum(exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr) -> Expr:
     ...
 
 
-@deprecated_alias(column="exprs")
+@deprecate_renamed_parameter("column", "exprs", version="0.18.7")
 def cumsum(
     exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr
 ) -> Expr | Series:

py-polars/polars/functions/lazy.py

@@ -26,7 +26,10 @@
     _time_to_pl_time,
     _timedelta_to_pl_timedelta,
 )
-from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
+from polars.utils.deprecation import (
+    deprecate_renamed_parameter,
+    issue_deprecation_warning,
+)
 
 with contextlib.suppress(ImportError):  # Module not available when building docs
     import polars.polars as plr
@@ -1806,7 +1809,9 @@ def arg_sort_by(
     return wrap_expr(plr.arg_sort_by(exprs, descending))
 
 
-@deprecated_alias(common_subplan_elimination="comm_subplan_elim")
+@deprecate_renamed_parameter(
+    "common_subplan_elimination", "comm_subplan_elim", version="0.18.9"
+)
 def collect_all(
     lazy_frames: Sequence[LazyFrame],
     *,

py-polars/polars/functions/range.py

@@ -11,7 +11,10 @@
 from polars.utils.convert import (
     _timedelta_to_pl_duration,
 )
-from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
+from polars.utils.deprecation import (
+    deprecate_renamed_parameter,
+    issue_deprecation_warning,
+)
 
 with contextlib.suppress(ImportError):  # Module not available when building docs
     import polars.polars as plr
@@ -66,7 +69,8 @@ def arange(
     ...
 
 
-@deprecated_alias(low="start", high="end")
+@deprecate_renamed_parameter("low", "start", version="0.18.0")
+@deprecate_renamed_parameter("high", "end", version="0.18.0")
 def arange(
     start: int | IntoExpr,
     end: int | IntoExpr,
@@ -370,7 +374,8 @@ def date_range(
     ...
 
 
-@deprecated_alias(low="start", high="end")
+@deprecate_renamed_parameter("low", "start", version="0.18.0")
+@deprecate_renamed_parameter("high", "end", version="0.18.0")
 def date_range(
     start: date | datetime | IntoExpr,
     end: date | datetime | IntoExpr,

py-polars/polars/functions/whenthen.py

@@ -5,7 +5,7 @@
 
 import polars._reexport as pl
 from polars.utils._parse_expr_input import parse_as_expression
-from polars.utils.deprecation import deprecated_alias
+from polars.utils.deprecation import deprecate_renamed_parameter
 
 with contextlib.suppress(ImportError):  # Module not available when building docs
     import polars.polars as plr
@@ -14,7 +14,7 @@
     from polars.type_aliases import IntoExpr
 
 
-@deprecated_alias(expr="condition")
+@deprecate_renamed_parameter("expr", "condition", version="0.18.9")
 def when(condition: IntoExpr) -> pl.When:
     """
     Start a `when-then-otherwise` expression.

py-polars/polars/io/database.py

@@ -6,14 +6,14 @@
 from typing import TYPE_CHECKING, Any
 
 from polars.convert import from_arrow
-from polars.utils.deprecation import deprecated_alias
+from polars.utils.deprecation import deprecate_renamed_parameter
 
 if TYPE_CHECKING:
     from polars import DataFrame
     from polars.type_aliases import DbReadEngine
 
 
-@deprecated_alias(connection_uri="connection")
+@deprecate_renamed_parameter("connection_uri", "connection", version="0.18.9")
 def read_database(
     query: list[str] | str,
     connection: str,

py-polars/polars/io/pyarrow_dataset/functions.py

@@ -3,7 +3,7 @@
 from typing import TYPE_CHECKING
 
 from polars.io.pyarrow_dataset.anonymous_scan import _scan_pyarrow_dataset
-from polars.utils.deprecation import deprecated_name
+from polars.utils.deprecation import deprecate_renamed_function
 
 if TYPE_CHECKING:
     from polars import LazyFrame
@@ -55,7 +55,7 @@ def scan_pyarrow_dataset(
     return _scan_pyarrow_dataset(source, allow_pyarrow_filter=allow_pyarrow_filter)
 
 
-@deprecated_name(new_name="scan_pyarrow_dataset", version="0.16.10")
+@deprecate_renamed_function(new_name="scan_pyarrow_dataset", version="0.16.10")
 def scan_ds(ds: pa.dataset.Dataset, *, allow_pyarrow_filter: bool = True) -> LazyFrame:
     """
     Scan a pyarrow dataset.