Deprecate df/ldf argument to .join (#3855)

py-polars/polars/internals/frame.py

@@ -67,6 +67,7 @@
 from polars.utils import (
     _prepare_row_count_args,
     _process_null_values,
+    deprecated_alias,
     format_path,
     handle_projection_columns,
     is_int_sequence,
@@ -3389,9 +3390,10 @@ def upsample(
             self._df.upsample(by, time_column, every, offset, maintain_order)
         )
 
+    @deprecated_alias(df="other")
     def join_asof(
         self: DF,
-        df: "DataFrame",
+        other: "DataFrame",
         left_on: Optional[str] = None,
         right_on: Optional[str] = None,
         on: Optional[str] = None,
@@ -3422,7 +3424,7 @@ def join_asof(
 
         Parameters
         ----------
-        ldf
+        other
             Lazy DataFrame to join with.
         left_on
             Join column of the left DataFrame.
@@ -3513,7 +3515,7 @@ def join_asof(
         return (
             self.lazy()
             .join_asof(
-                df.lazy(),
+                other.lazy(),
                 left_on=left_on,
                 right_on=right_on,
                 on=on,
@@ -3529,9 +3531,10 @@ def join_asof(
             .collect(no_optimization=True)
         )
 
+    @deprecated_alias(df="other")
     def join(
         self: DF,
-        df: "DataFrame",
+        other: "DataFrame",
         left_on: Optional[Union[str, "pli.Expr", List[Union[str, "pli.Expr"]]]] = None,
         right_on: Optional[Union[str, "pli.Expr", List[Union[str, "pli.Expr"]]]] = None,
         on: Optional[Union[str, "pli.Expr", List[Union[str, "pli.Expr"]]]] = None,
@@ -3546,7 +3549,7 @@ def join(
 
         Parameters
         ----------
-        df
+        other
             DataFrame to join with.
         left_on
             Name(s) of the left join column(s).
@@ -3633,7 +3636,7 @@ def join(
                 DeprecationWarning,
             )
         if how == "cross":
-            return self._from_pydf(self._df.join(df._df, [], [], how, suffix))
+            return self._from_pydf(self._df.join(other._df, [], [], how, suffix))
 
         left_on_: Optional[List[Union[str, pli.Expr]]]
         if isinstance(left_on, (str, pli.Expr)):
@@ -3667,7 +3670,7 @@ def join(
             return (
                 self.lazy()
                 .join(
-                    df.lazy(),
+                    other.lazy(),
                     left_on,
                     right_on,
                     on=on,
@@ -3681,7 +3684,7 @@ def join(
             )
         else:
             return self._from_pydf(
-                self._df.join(df._df, left_on_, right_on_, how, suffix)
+                self._df.join(other._df, left_on_, right_on_, how, suffix)
             )
 
     def apply(

py-polars/polars/internals/lazy_frame.py

@@ -43,6 +43,7 @@
     _in_notebook,
     _prepare_row_count_args,
     _process_null_values,
+    deprecated_alias,
     format_path,
 )
 
@@ -1121,9 +1122,10 @@ def groupby_dynamic(
         )
         return LazyGroupBy(lgb, lazyframe_class=self.__class__)
 
+    @deprecated_alias(ldf="other")
     def join_asof(
         self: LDF,
-        ldf: "LazyFrame",
+        other: "LazyFrame",
         left_on: Optional[str] = None,
         right_on: Optional[str] = None,
         on: Optional[str] = None,
@@ -1154,7 +1156,7 @@ def join_asof(
 
         Parameters
         ----------
-        ldf
+        other
             Lazy DataFrame to join with.
         left_on
             Join column of the left DataFrame.
@@ -1197,8 +1199,8 @@ def join_asof(
         force_parallel
             Force the physical plan to evaluate the computation of both DataFrames up to the join in parallel.
         """
-        if not isinstance(ldf, LazyFrame):
-            raise ValueError(f"Expected a `LazyFrame` as join table, got {type(ldf)}")
+        if not isinstance(other, LazyFrame):
+            raise ValueError(f"Expected a `LazyFrame` as join table, got {type(other)}")
 
         if isinstance(on, str):
             left_on = on
@@ -1235,7 +1237,7 @@ def join_asof(
 
         return self._from_pyldf(
             self._ldf.join_asof(
-                ldf._ldf,
+                other._ldf,
                 pli.col(left_on)._pyexpr,
                 pli.col(right_on)._pyexpr,
                 by_left_,
@@ -1249,9 +1251,10 @@ def join_asof(
             )
         )
 
+    @deprecated_alias(ldf="other")
     def join(
         self: LDF,
-        ldf: "LazyFrame",
+        other: "LazyFrame",
         left_on: Optional[Union[str, "pli.Expr", List[Union[str, "pli.Expr"]]]] = None,
         right_on: Optional[Union[str, "pli.Expr", List[Union[str, "pli.Expr"]]]] = None,
         on: Optional[Union[str, "pli.Expr", List[Union[str, "pli.Expr"]]]] = None,
@@ -1268,7 +1271,7 @@ def join(
 
         Parameters
         ----------
-        ldf
+        other
             Lazy DataFrame to join with.
         left_on
             Join column of the left DataFrame.
@@ -1346,8 +1349,8 @@ def join(
         └──────┴──────┴─────┴───────┘
 
         """
-        if not isinstance(ldf, LazyFrame):
-            raise ValueError(f"Expected a `LazyFrame` as join table, got {type(ldf)}")
+        if not isinstance(other, LazyFrame):
+            raise ValueError(f"Expected a `LazyFrame` as join table, got {type(other)}")
 
         if how == "asof":
             warnings.warn(
@@ -1357,7 +1360,7 @@ def join(
         if how == "cross":
             return self._from_pyldf(
                 self._ldf.join(
-                    ldf._ldf,
+                    other._ldf,
                     [],
                     [],
                     allow_parallel,
@@ -1430,7 +1433,7 @@ def join(
 
         return self._from_pyldf(
             self._ldf.join(
-                ldf._ldf,
+                other._ldf,
                 new_left_on,
                 new_right_on,
                 allow_parallel,

py-polars/polars/utils.py

@@ -1,9 +1,22 @@
 import ctypes
+import functools
 import os
 import sys
+import warnings
 from datetime import date, datetime, time, timedelta, timezone
 from pathlib import Path
-from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Type, Union
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Sequence,
+    Tuple,
+    Type,
+    Union,
+)
 
 import numpy as np
 
@@ -244,3 +257,46 @@ def threadpool_size() -> int:
     Get the size of polars; thread pool
     """
     return _pool_size()
+
+
+def deprecated_alias(**aliases: str) -> Callable:
+    """Decorator for deprecated function and method arguments.
+
+    Use as follows:
+
+    @deprecated_alias(old_arg='new_arg')
+    def myfunc(new_arg):
+        ...
+    """
+
+    def deco(f: Callable) -> Callable:
+        @functools.wraps(f)
+        def wrapper(*args: Any, **kwargs: Any) -> Callable:
+            rename_kwargs(f.__name__, kwargs, aliases)
+            return f(*args, **kwargs)
+
+        return wrapper
+
+    return deco
+
+
+def rename_kwargs(
+    func_name: str, kwargs: Dict[str, str], aliases: Dict[str, str]
+) -> None:
+    """Helper function for deprecating function and method arguments."""
+    for alias, new in aliases.items():
+        if alias in kwargs:
+            if new in kwargs:
+                raise TypeError(
+                    f"{func_name} received both {alias} and {new} as arguments!"
+                    f" {alias} is deprecated, use {new} instead."
+                )
+            warnings.warn(
+                message=(
+                    f"`{alias}` is deprecated as an argument to `{func_name}`; use"
+                    f" `{new}` instead."
+                ),
+                category=DeprecationWarning,
+                stacklevel=3,
+            )
+            kwargs[new] = kwargs.pop(alias)

py-polars/tests/test_joins.py

@@ -1,6 +1,7 @@
 from datetime import datetime
 
 import numpy as np
+import pytest
 
 import polars as pl
 
@@ -180,3 +181,20 @@ def test_join_asof_tolerance() -> None:
         "trade": [101, 299, 301, 500],
         "quote": [100, None, 300, None],
     }
+
+
+def test_deprecated() -> None:
+    df = pl.DataFrame({"a": [1, 2], "b": [3, 4]})
+    other = pl.DataFrame({"a": [1, 2], "c": [3, 4]})
+    result = pl.DataFrame({"a": [1, 2], "b": [3, 4], "c": [3, 4]})
+
+    with pytest.deprecated_call():
+        df.join(df=other, on="a")
+    with pytest.deprecated_call():
+        df.lazy().join(ldf=other.lazy(), on="a").collect()
+
+    np.testing.assert_equal(df.join(other=other, on="a").to_numpy(), result.to_numpy())
+    np.testing.assert_equal(
+        df.lazy().join(other=other.lazy(), on="a").collect().to_numpy(),
+        result.to_numpy(),
+    )