Skip to content

DOC: clarify reduction method docstrings#65858

Open
J270697 wants to merge 4 commits into
pandas-dev:mainfrom
J270697:doc-clarify-reduction-docstrings
Open

DOC: clarify reduction method docstrings#65858
J270697 wants to merge 4 commits into
pandas-dev:mainfrom
J270697:doc-clarify-reduction-docstrings

Conversation

@J270697

@J270697 J270697 commented Jun 11, 2026

Copy link
Copy Markdown

This PR clarifies several reduction method docstrings.

It updates Series.mean and DataFrame.mean based on feedback from the pandas newcomers meeting by @jorisvandenbossche, including clearer axis wording, removal of DataFrame-specific wording from Series.mean, and a shorter See Also section for DataFrame.mean. It also clarifies that **kwargs for related reduction methods are accepted for NumPy compatibility when using default values.

Observations:

  • The explanation for kwargs is unclear/misleading ("Additional keyword arguments to be passed to the function."), because there actually no additional arguments. There are only some arguments (like keepdim) that are accepted for compatibility with numpy, and only if they have the default value of np.mean()
  • For the Series case, the first sentence "Return the mean of the values over the requested axis" can be simplified (the axis keyword is ignored for Series)
  • The "See Also" section for DataFrame.mean could be trimmed a bit (only reference the other DataFrame ones, and not the Series ones)
  • For the axis keyword, it is not clear that the option index can actually be passed as a string "index"
  • For DataFrame axis keyword, no need to mention it is ignored for Series.

Validations Ran:

  • git diff --check
  • python -m pytest pandas/tests/frame/test_reductions.py -k "min or max or sum or prod or mean or median or std"
  • python -m pytest pandas/tests/series/test_reductions.py -k "min or max or sum or prod or mean or median"
  • python doc/make.py --warnings-are-errors --no-browser --single pandas.Series.mean
  • python doc/make.py --warnings-are-errors --no-browser --single pandas.DataFrame.mean

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants