Update join docs for other param (pandas-dev#46850)

* Update join docs for other param

Update join docs regarding using multiple Series

* Update type for _join_compat

* Allow any iterable for join; test join for a list of series

* Update type signature

* Update pd.concat type, add cast() to make frame.join() work with mypy

* Fix type union syntax

* NDFrame

* Remove cast

* Fix mypy errors

* Code review

* Remove unnecessary assert

* Add comment explaining the cast

* Fix swapped order of cast comment

* Remove full stop

* Update pandas/core/frame.py

Co-authored-by: Marc Garcia <[email protected]>

Author: multimeric

pandas/core/frame.py

@@ -9788,7 +9788,7 @@ def _append(
 
     def join(
         self,
-        other: DataFrame | Series,
+        other: DataFrame | Series | list[DataFrame | Series],
         on: IndexLabel | None = None,
         how: str = "left",
         lsuffix: str = "",
@@ -9805,7 +9805,7 @@ def join(
 
         Parameters
         ----------
-        other : DataFrame, Series, or list of DataFrame
+        other : DataFrame, Series, or a list containing any combination of them
             Index should be similar to one of the columns in this one. If a
             Series is passed, its name attribute must be set, and that will be
             used as the column name in the resulting joined DataFrame.
@@ -9961,7 +9961,7 @@ def join(
 
     def _join_compat(
         self,
-        other: DataFrame | Series,
+        other: DataFrame | Series | Iterable[DataFrame | Series],
         on: IndexLabel | None = None,
         how: str = "left",
         lsuffix: str = "",
@@ -10010,7 +10010,11 @@ def _join_compat(
                     "Suffixes not supported when joining multiple DataFrames"
                 )
 
-            frames = [self] + list(other)
+            # Mypy thinks the RHS is a
+            # "Union[DataFrame, Series, Iterable[Union[DataFrame, Series]]]" whereas
+            # the LHS is an "Iterable[DataFrame]", but in reality both types are
+            # "Iterable[Union[DataFrame, Series]]" due to the if statements
+            frames = [cast("DataFrame | Series", self)] + list(other)
 
             can_concat = all(df.index.is_unique for df in frames)
 

pandas/tests/frame/methods/test_join.py

@@ -367,6 +367,15 @@ def test_join_left_sequence_non_unique_index():
     tm.assert_frame_equal(joined, expected)
 
 
+def test_join_list_series(float_frame):
+    # GH#46850
+    # Join a DataFrame with a list containing both a Series and a DataFrame
+    left = float_frame.A.to_frame()
+    right = [float_frame.B, float_frame[["C", "D"]]]
+    result = left.join(right)
+    tm.assert_frame_equal(result, float_frame)
+
+
 @pytest.mark.parametrize("sort_kw", [True, False])
 def test_suppress_future_warning_with_sort_kw(sort_kw):
     a = DataFrame({"col1": [1, 2]}, index=["c", "a"])