From the discussion in PR #36409 it was mentioned that it is undesirable to type API functions as NDFrame as this may be confusing from a user perspective since it shows up in the docs. Currently the difference between NDFrame and FrameOrSeriesUnion = Union[DataFrame, Series] is that the former can be used in methods of NDFrame (and those called from NDFrame methods) whereas the latter cannot.

Is there a benefit to this restriction? If not, I propose changing FrameOrSeriesUnion to be an alias of NDFrame. This would then be user-friendly for the docs.

cc @simonjayhawkins @WillAyd @jreback

Comment From: simonjayhawkins

This would then be user-friendly for the docs.

at the moment, sphinx expands the aliases rather than showing the alias. see return type of https://pandas.pydata.org/pandas-docs/dev/reference/api/pandas.concat.html

29480 sort of related as well.

Comment From: rhshadrach

Thanks for the background @simonjayhawkins. I see a different result here:

https://pandas.pydata.org/docs/reference/api/pandas.concat.html

where the type-hints are not expanded. Is this a recent change that will impact the 1.2 docs when released?

Comment From: simonjayhawkins

tbh, not even sure why they are appearing for pd.concat in html docs as they as supposed to be disabled, see #33312

for normal python help...

>>> import pandas as pd
>>> help(pd.concat)
Help on function concat in module pandas.core.reshape.concat:

concat(objs: Union[Iterable[ForwardRef('NDFrame')], Mapping[Union[Hashable, NoneType], ForwardRef('NDFrame')]], axis=0, join='outer', ignore_index: bool = False, keys=No
ne, levels=None, names=None, verify_integrity: bool = False, sort: bool = False, copy: bool = True) -> Union[ForwardRef('DataFrame'), ForwardRef('Series')]

it even includes the ForwardRef! (this can now be removed, but not for backports, see #36034)

Comment From: rhshadrach

@simonjayhawkins This is an issue with Sphinx, currently open:

https://github.com/sphinx-doc/sphinx/issues/7785

Comment From: simonjayhawkins

From the discussion in PR #36409 it was mentioned that it is undesirable to type API functions as NDFrame as this may be confusing from a user perspective since it shows up in the docs.

type annotations are no longer displayed in the docs

If not, I propose changing FrameOrSeriesUnion to be an alias of NDFrame

no longer relevant. #41955

Pandas TYP: FrameOrSeriesUnion

29480 sort of related as well.