DOC: `Series.sum()` has examples that don't illustrate the actual results

[Dr-Irv]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.Series.sum.html

Documentation problem

Consider this example from the docs:

>>> idx = pd.MultiIndex.from_arrays(
...     [["warm", "warm", "cold", "cold"], ["dog", "falcon", "fish", "spider"]],
...     names=["blooded", "animal"],
... )
>>> s = pd.Series([4, 2, 0, 8], name="legs", index=idx)
>>> s.sum()

The docs indicate that s.sum() is 14.
But at runtime, it is an np.int64:

>>> s.sum()
np.int64(14)

But the printed result depends on the backend:

>>> s = pd.Series([4,2,0,8], name="legs", index=idx, dtype="int64[pyarrow]")
>>> s.sum()
14

The example results are hard coded in the docs, and are not created by executing the code (as in other doc areas).

Suggested fix for documentation

Not sure. Do we fix the docs so that it executes the code rather than have hard coded results?

Do we want to indicate whether we are returning numpy types or python types?

[bdipesh3045]

Hi, I’d like to work on this issue if it’s still available.
I’ve gone through the example and confirmed the discrepancy.
Could you please assign it to me?

[Dr-Irv]

Hi, I’d like to work on this issue if it’s still available. I’ve gone through the example and confirmed the discrepancy. Could you please assign it to me?

I'd like to get comments from other pandas developers so we decide what we want to do.

[rhshadrach]

The result is only wrong when using numpy>=2. We build our docs and run doctests with numpy<2. Not sure if there is anything holding us back from changing the pin in environment.yml, cc @mroeschke.

[mroeschke]

I think environment.yml is pinned because of this repr difference, possibly because it was tedious to update all these docstrings. I would be OK unpinning numpy

[rhshadrach]

It seems to me enough time has passed since 2.0 has come out. I can take on updating the reprs.

[Dr-Irv]

It seems to me enough time has passed since 2.0 has come out. I can take on updating the reprs.

2 notes here:

1. At least for sum(), the results are hard coded in the docs, i.e., they are not generated when the docs are compiled.
2. We get different __repr__ results dependent on the dtype (e.g., dtype=int vs. dtype=int64[pyarrow]

Not sure what is the right thing to do here.

[rhshadrach]

It's not clear to me what isn't clear. All of our docstring have hard coded results. And I'm negative on not having the results hard coded in the docstring, it is useful to have the hard coded results when looking at docs that aren't on the web.

[Dr-Irv]

t's not clear to me what isn't clear. All of our docstring have hard coded results. And I'm negative on not having the results hard coded in the docstring, it is useful to have the hard coded results when looking at docs that aren't on the web.

My mistake. I thought we generated results, but I guess that's only true for the pure doc pages, not the docs for methods/functions/classes.

We still have the issue of different results dependent on the underlying dtypes.

[rhshadrach]

We still have the issue of different results dependent on the underlying dtypes.

I would suggest a separate issue for this, our issue tracker is currently littered with various instances which could be replaced by one tracking issue.

#60560
#25969
#35656
#35475

[Dr-Irv]

We still have the issue of different results dependent on the underlying dtypes.

I would suggest a separate issue for this, our issue tracker is currently littered with various instances which could be replaced by one tracking issue.

Maybe, but those are about the behavior of pandas.

Here, my question is how we want to document it. If we show that Series.sum() shows results that are numpy types, that's not entirely correct, because the underlying dtype would change the result.

And I don't think the docs should imply that you get a numpy type from that method.