DOC: Clarify broadcasting behavior when using lists in DataFrame arithmetic (GH18857)

doc/source/user_guide/basics.rst

@@ -209,6 +209,10 @@ either match on the *index* or *columns* via the **axis** keyword:
    df.sub(column, axis="index")
    df.sub(column, axis=0)
 
+Be careful when using raw Python lists in binary operations with DataFrames.
+Unlike NumPy arrays or Series, lists are not broadcast across rows or columns.
+Instead, pandas attempts to match the entire list against a single axis, which may lead to confusing results such as Series of arrays.
+To ensure proper broadcasting behavior, use a NumPy array or Series with explicit index or shape.
 Furthermore you can align a level of a MultiIndexed DataFrame with a Series.
 
 .. ipython:: python

doc/source/user_guide/dsintro.rst

@@ -650,6 +650,19 @@ row-wise. For example:
 
    df - df.iloc[0]
 
+When using a Python list in arithmetic operations with a DataFrame, the behavior is not element-wise broadcasting.
+Instead, the list is treated as a single object and the operation is performed column-wise, resulting in unexpected output (e.g. arrays inside each cell).
+
+.. ipython:: python
+
+    df = pd.DataFrame(np.arange(6).reshape(2, 3), columns=["A", "B", "C"])
+
+    df + [1, 2, 3]  # Returns a Series of arrays, not a DataFrame
+
+    df + np.array([1, 2, 3])  # Correct broadcasting
+
+    df + pd.Series([1, 2, 3], index=["A", "B", "C"])  # Also correct
+
 For explicit control over the matching and broadcasting behavior, see the
 section on :ref:`flexible binary operations <basics.binop>`.