refactor(python): Add a simple util issue_deprecation_warning (#10146)

py-polars/polars/dataframe/frame.py

@@ -4,7 +4,6 @@
 import contextlib
 import os
 import random
-import warnings
 from collections import defaultdict
 from collections.abc import Sized
 from io import BytesIO, StringIO, TextIOWrapper
@@ -87,12 +86,11 @@
 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.decorators import deprecated_alias
+from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
 from polars.utils.various import (
     _prepare_row_count_args,
     _process_null_values,
     can_create_dicts_with_pyarrow,
-    find_stacklevel,
     handle_projection_columns,
     is_bool_sequence,
     is_int_sequence,
@@ -6550,12 +6548,10 @@ def pivot(
             columns = [columns]
 
         if aggregate_function is no_default:
-            warnings.warn(
+            issue_deprecation_warning(
                 "In a future version of polars, the default `aggregate_function` "
                 "will change from `'first'` to `None`. Please pass `'first'` to keep the "
-                "current behaviour, or `None` to accept the new one.",
-                DeprecationWarning,
-                stacklevel=find_stacklevel(),
+                "current behaviour, or `None` to accept the new one."
             )
             aggregate_function = "first"
 

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.decorators import deprecated_alias
+from polars.utils.deprecation import deprecated_alias
 
 if TYPE_CHECKING:
     from datetime import timedelta

py-polars/polars/expr/expr.py

@@ -50,7 +50,7 @@
     parse_as_list_of_expressions,
 )
 from polars.utils.convert import _timedelta_to_pl_duration
-from polars.utils.decorators import (
+from polars.utils.deprecation import (
     deprecated,
     deprecated_alias,
     warn_closed_future_change,

py-polars/polars/expr/list.py

@@ -7,7 +7,7 @@
 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.decorators import deprecated_alias
+from polars.utils.deprecation import deprecated_alias
 
 if TYPE_CHECKING:
     from datetime import date, datetime, time

py-polars/polars/expr/string.py

@@ -7,7 +7,7 @@
 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.decorators import deprecated_alias
+from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
 from polars.utils.various import find_stacklevel
 
 if TYPE_CHECKING:
@@ -136,14 +136,12 @@ def to_datetime(
         """
         _validate_format_argument(format)
         if utc is not None:
-            warnings.warn(
+            issue_deprecation_warning(
                 "The `utc` argument is now a no-op and has no effect. "
                 "You can safely remove it. "
                 "Offset-naive strings are parsed as ``pl.Datetime(time_unit)``, "
                 "and offset-aware strings are converted to "
-                '``pl.Datetime(time_unit, "UTC")``.',
-                DeprecationWarning,
-                stacklevel=find_stacklevel(),
+                '``pl.Datetime(time_unit, "UTC")``.'
             )
         return wrap_expr(
             self._pyexpr.str_to_datetime(

py-polars/polars/expr/whenthen.py

@@ -1,14 +1,12 @@
 from __future__ import annotations
 
-import warnings
 from typing import TYPE_CHECKING, Any
 
 import polars.functions as F
 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.decorators import deprecated_alias
-from polars.utils.various import find_stacklevel
+from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
 
 if TYPE_CHECKING:
     from polars.polars import PyExpr
@@ -182,9 +180,7 @@ def otherwise(self, statement: IntoExpr) -> Expr:
 
 
 def _warn_for_deprecated_string_input_behavior(input: str) -> None:
-    warnings.warn(
+    issue_deprecation_warning(
         "in a future version, string input will be parsed as a column name rather than a string literal."
-        f" To silence this warning, pass the input as an expression instead: `pl.lit({input!r})`",
-        DeprecationWarning,
-        stacklevel=find_stacklevel(),
+        f" To silence this warning, pass the input as an expression instead: `pl.lit({input!r})`"
     )

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

@@ -1,12 +1,10 @@
 from __future__ import annotations
 
-import warnings
 from typing import TYPE_CHECKING, Any, Iterable, overload
 
 import polars._reexport as pl
 import polars.functions as F
-from polars.utils.decorators import deprecated_alias
-from polars.utils.various import find_stacklevel
+from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
 
 if TYPE_CHECKING:
     from polars import Expr, Series
@@ -91,10 +89,8 @@ def all(
         if exprs is None:
             return F.col("*")
         elif isinstance(exprs, pl.Series):
-            warnings.warn(
-                "passing a Series to `all` is deprecated. Use `Series.all()` instead.",
-                DeprecationWarning,
-                stacklevel=find_stacklevel(),
+            issue_deprecation_warning(
+                "passing a Series to `all` is deprecated. Use `Series.all()` instead."
             )
             return exprs.all()
         elif isinstance(exprs, str):
@@ -163,10 +159,8 @@ def any(
     """
     if not more_exprs:
         if isinstance(exprs, pl.Series):
-            warnings.warn(
-                "passing a Series to `any` is deprecated. Use `Series.any()` instead.",
-                DeprecationWarning,
-                stacklevel=find_stacklevel(),
+            issue_deprecation_warning(
+                "passing a Series to `any` is deprecated. Use `Series.any()` instead."
             )
             return exprs.any()
         elif isinstance(exprs, str):
@@ -257,10 +251,8 @@ def max(exprs: IntoExpr | Iterable[IntoExpr], *more_exprs: IntoExpr) -> Expr | A
     """
     if not more_exprs:
         if isinstance(exprs, pl.Series):
-            warnings.warn(
-                "passing a Series to `max` is deprecated. Use `Series.max()` instead.",
-                DeprecationWarning,
-                stacklevel=find_stacklevel(),
+            issue_deprecation_warning(
+                "passing a Series to `max` is deprecated. Use `Series.max()` instead."
             )
             return exprs.max()
         elif isinstance(exprs, str):
@@ -353,10 +345,8 @@ def min(
     """
     if not more_exprs:
         if isinstance(exprs, pl.Series):
-            warnings.warn(
-                "passing a Series to `min` is deprecated. Use `Series.min()` instead.",
-                DeprecationWarning,
-                stacklevel=find_stacklevel(),
+            issue_deprecation_warning(
+                "passing a Series to `min` is deprecated. Use `Series.min()` instead."
             )
             return exprs.min()
         elif isinstance(exprs, str):
@@ -450,10 +440,8 @@ def sum(
     """
     if not more_exprs:
         if isinstance(exprs, pl.Series):
-            warnings.warn(
-                "passing a Series to `sum` is deprecated. Use `Series.sum()` instead.",
-                DeprecationWarning,
-                stacklevel=find_stacklevel(),
+            issue_deprecation_warning(
+                "passing a Series to `sum` is deprecated. Use `Series.sum()` instead."
             )
             return exprs.sum()
         elif isinstance(exprs, str):
@@ -524,10 +512,8 @@ def cumsum(
     """
     if not more_exprs:
         if isinstance(exprs, pl.Series):
-            warnings.warn(
-                "passing a Series to `cumsum` is deprecated. Use `Series.cumsum()` instead.",
-                DeprecationWarning,
-                stacklevel=find_stacklevel(),
+            issue_deprecation_warning(
+                "passing a Series to `cumsum` is deprecated. Use `Series.cumsum()` instead."
             )
             return exprs.cumsum()
         elif isinstance(exprs, str):
@@ -538,8 +524,6 @@ def cumsum(
 
 
 def _warn_for_deprecated_horizontal_use(name: str) -> None:
-    warnings.warn(
-        f"using `{name}` for horizontal computation is deprecated. Use `{name}_horizontal` instead.",
-        DeprecationWarning,
-        stacklevel=find_stacklevel(),
+    issue_deprecation_warning(
+        f"using `{name}` for horizontal computation is deprecated. Use `{name}_horizontal` instead."
     )

py-polars/polars/functions/as_datatype.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import contextlib
-import warnings
 from typing import TYPE_CHECKING, Iterable, overload
 
 from polars import functions as F
@@ -11,7 +10,7 @@
     parse_as_list_of_expressions,
 )
 from polars.utils._wrap import wrap_expr
-from polars.utils.various import find_stacklevel
+from polars.utils.deprecation import issue_deprecation_warning
 
 with contextlib.suppress(ImportError):  # Module not available when building docs
     import polars.polars as plr
@@ -376,11 +375,9 @@ def struct(
 
     """
     if "exprs" in named_exprs:
-        warnings.warn(
+        issue_deprecation_warning(
             "passing expressions to `struct` using the keyword argument `exprs` is"
-            " deprecated. Use positional syntax instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+            " deprecated. Use positional syntax instead."
         )
         first_input = named_exprs.pop("exprs")
         pyexprs = parse_as_list_of_expressions(first_input, *exprs, **named_exprs)

py-polars/polars/functions/lazy.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import contextlib
-import warnings
 from datetime import date, datetime, time, timedelta
 from typing import TYPE_CHECKING, Any, Callable, Iterable, Sequence, overload
 
@@ -27,8 +26,7 @@
     _time_to_pl_time,
     _timedelta_to_pl_timedelta,
 )
-from polars.utils.decorators import deprecated_alias
-from polars.utils.various import find_stacklevel
+from polars.utils.deprecation import deprecated_alias, issue_deprecation_warning
 
 with contextlib.suppress(ImportError):  # Module not available when building docs
     import polars.polars as plr
@@ -323,10 +321,8 @@ def count(column: str | Series | None = None) -> Expr | int:
         return wrap_expr(plr.count())
 
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `count` is deprecated. Use `Series.len()` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `count` is deprecated. Use `Series.len()` instead."
         )
         return column.len()
     return col(column).count()
@@ -385,10 +381,8 @@ def std(column: str | Series, ddof: int = 1) -> Expr | float | None:
 
     """
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `std` is deprecated. Use `Series.std()` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `std` is deprecated. Use `Series.std()` instead."
         )
         return column.std(ddof)
     return col(column).std(ddof)
@@ -434,10 +428,8 @@ def var(column: str | Series, ddof: int = 1) -> Expr | float | None:
 
     """
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `var` is deprecated. Use `Series.var()` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `var` is deprecated. Use `Series.var()` instead."
         )
         return column.var(ddof)
     return col(column).var(ddof)
@@ -472,10 +464,8 @@ def mean(column: str | Series) -> Expr | float | None:
 
     """
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `mean` is deprecated. Use `Series.mean()` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `mean` is deprecated. Use `Series.mean()` instead."
         )
         return column.mean()
     return col(column).mean()
@@ -541,10 +531,8 @@ def median(column: str | Series) -> Expr | float | int | None:
 
     """
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `median` is deprecated. Use `Series.median()` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `median` is deprecated. Use `Series.median()` instead."
         )
         return column.median()
     return col(column).median()
@@ -579,10 +567,8 @@ def n_unique(column: str | Series) -> Expr | int:
 
     """
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `n_unique` is deprecated. Use `Series.n_unique()` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `n_unique` is deprecated. Use `Series.n_unique()` instead."
         )
         return column.n_unique()
     return col(column).n_unique()
@@ -674,10 +660,8 @@ def first(column: str | Series | None = None) -> Expr | Any:
         return wrap_expr(plr.first())
 
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `first` is deprecated. Use `series[0]` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `first` is deprecated. Use `series[0]` instead."
         )
         if column.len() > 0:
             return column[0]
@@ -740,10 +724,8 @@ def last(column: str | Series | None = None) -> Expr:
         return wrap_expr(plr.last())
 
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `last` is deprecated. Use `series[-1]` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `last` is deprecated. Use `series[-1]` instead."
         )
         if column.len() > 0:
             return column[-1]
@@ -800,10 +782,8 @@ def head(column: str | Series, n: int = 10) -> Expr | Series:
 
     """
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `head` is deprecated. Use `Series.head()` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `head` is deprecated. Use `Series.head()` instead."
         )
         return column.head(n)
     return col(column).head(n)
@@ -857,10 +837,8 @@ def tail(column: str | Series, n: int = 10) -> Expr | Series:
 
     """
     if isinstance(column, pl.Series):
-        warnings.warn(
-            "passing a Series to `tail` is deprecated. Use `Series.tail()` instead.",
-            DeprecationWarning,
-            stacklevel=find_stacklevel(),
+        issue_deprecation_warning(
+            "passing a Series to `tail` is deprecated. Use `Series.tail()` instead."
         )
         return column.tail(n)
     return col(column).tail(n)