BUG: wrong type hint for pandas.Series.droplevel

[sz-cgt]

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

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

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

---

Note: Please read this guide detailing how to provide the necessary information for us to reproduce your bug.

Code Sample, a copy-pastable example

type(pandas.Series({("a", 1): 1, ("a", 2): 2, ("b", 1): 3, ("b", 4): 4}).droplevel(level=1))

Problem description

Both the type hint for pandas.Series.droplevel() and the documentation say the function returns a DataFrame.

However, it clearly returns a Series.

While not a Bug per se, this does violate the Law of Least Suprise

Output of pd.show_versions()

pandas.show_versions()

INSTALLED VERSIONS

commit : 7d32926
python : 3.8.5.final.0
python-bits : 64
OS : Linux
OS-release : 4.19.104-microsoft-standard
Version : #1 SMP Wed Feb 19 06:37:35 UTC 2020
machine : x86_64
processor : x86_64
byteorder : little
LC_ALL : None
LANG : C.UTF-8
LOCALE : en_US.UTF-8

pandas : 1.2.2
numpy : 1.20.1
pytz : 2021.1
dateutil : 2.8.1
pip : 20.0.2
setuptools : 44.0.0
Cython : None
pytest : None
hypothesis : None
sphinx : None
blosc : None
feather : None
xlsxwriter : None
lxml.etree : None
html5lib : 1.0.1
pymysql : None
psycopg2 : None
jinja2 : None
IPython : None
pandas_datareader: None
bs4 : None
bottleneck : None
fsspec : None
fastparquet : None
gcsfs : None
matplotlib : None
numexpr : None
odfpy : None
openpyxl : 3.0.6
pandas_gbq : None
pyarrow : 0.17.1
pyxlsb : None
s3fs : None
scipy : None
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : None
xlwt : None
numba : None

[MarcoGorelli]

Thanks @sz-cgt - looks like this docstring needs a substitution (see other methods in that file which have @doc), do you want to open a pull request to fix this? If so, here's the contributing guide

[Muktan]

@MarcoGorelli, I came up with a solution with docstring substitution as follows.

...
+@doc(klass=_shared_doc_kwargs["klass"])
    def droplevel(self: FrameOrSeries, level, axis=0) -> FrameOrSeries:
        """
        Return {klass} with requested index / column level(s) removed.
        ...

Is this the expected behavior:-

I am not sure if it is ok to have Series/DataFrame in Returns.

[MarcoGorelli]

@Muktan looks fine to me (this method is marked @final so it can't be overridden anyway) - want to open a PR?

[Muktan]

Will do it right away.