DOC: Broadcasting for binary operators

[jamesmyatt]

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the master branch of pandas.

Reproducible Example

import pandas as pd
df = pd.DataFrame({"A": [1, 2], "B": [2, 0], "C": [4, 2]}, index=["AA", "BB"])

# Add half of column C to the other two columns
df[["A", "B"]] + df["C"] / 2

Issue Description

I'm marked this as a bug because I am under the impression that this worked as I expected in a previous version, but I can't be sure.

I had assumed that this operator would intelligently align the series with the columns of the data frame, since the index of the series is the same object as the index of the dataframe, rather than defaulting to axis="columns" as for the add method.

Above gives

	A	AA	B	BB
AA	NaN	NaN	NaN	NaN
BB	NaN	NaN	NaN	NaN

It feels like the operator versions of the binary operations could have the additional logic to attempt to intelligently choose which axis to use to broadcast when operating on a dataframe and a series. If you need to specific the axis for speed or because it's possible to make the wrong choice, then I think it's OK to expect people to use the method version.

However, if this is the intended behaviour, then it's probably worth adding something in the docs. In fact, I can't find any documentation for the operator versions and there's no docstring. In particular, how is __add__ different from add? Because they're implemented differently, and you can't be sure that a + b and a.add(b) will return the same result by inspecting the code.

> ?df.__add__

Signature: df.__add__(other)
Docstring: <no docstring>
File:      __conda_env__\lib\site-packages\pandas\core\arraylike.py
Type:      method

Expected Behavior

Like

df[["A", "B"]].add(df["C"] / 2, axis=0)

only since

df[["A", "B"]].index is (df["C"] / 2).index

	A	B
AA	3.0	4.0
BB	3.0	1.0

Installed Versions

INSTALLED VERSIONS
------------------
commit           : 73c68257545b5f8530b7044f56647bd2db92e2ba
python           : 3.9.7.final.0
python-bits      : 64
OS               : Windows
OS-release       : 10
Version          : 10.0.18363
machine          : AMD64
processor        : Intel64 Family 6 Model 142 Stepping 12, GenuineIntel
byteorder        : little
LC_ALL           : None
LANG             : en_GB.UTF-8
LOCALE           : English_United Kingdom.1252

pandas           : 1.3.3
numpy            : 1.21.2
pytz             : 2021.3
dateutil         : 2.8.2
pip              : 21.2.4
setuptools       : 58.2.0
Cython           : None
pytest           : None
hypothesis       : None
sphinx           : None
blosc            : None
feather          : None
xlsxwriter       : None
lxml.etree       : None
html5lib         : None
pymysql          : None
psycopg2         : None
jinja2           : 3.0.2
IPython          : 7.28.0
pandas_datareader: None
bs4              : None
bottleneck       : 1.3.2
fsspec           : None
fastparquet      : None
gcsfs            : None
matplotlib       : 3.4.3
numexpr          : 2.7.3
odfpy            : None
openpyxl         : None
pandas_gbq       : None
pyarrow          : None
pyxlsb           : None
s3fs             : None
scipy            : None
sqlalchemy       : None
tables           : None
tabulate         : 0.8.9
xarray           : None
xlrd             : None
xlwt             : None
numba            : None

[jessica-writes-code]

take