DOC: definition of a scalar in rich comparison methods

[cmp0xff]

This was inspired by #62063 (comment) and will relax the philosophical tension that caused the closure of pandas-dev/pandas-stubs#1288.

• closes BUG: is_scalar(Enum) gives False #62063

[jbrockmendel]

Anything can be an element of a series.

[cmp0xff]

Hi @jbrockmendel, thank you for the quick review.

The original docs can potentially imply that only scalars recognised by Pandas can be accepted as arguments in .eq, .ge, etc. And scalars recognised by Pandas means variables passing the is_scalar test.

This is not true. An Enum, for example, fails the is_scalar test, but it can be the elements of a Pandas Series, and series.eq(some_enum) works fine at runtime.

This PR aims to remove the potential misinterpretation of the original documentation.

[rhshadrach]

The parentheses added here do not help the issue since any Python object can be an element of a Series (even a Series itself can be an element of a Series!). We want to indicate that this method treats lists, tuples, ndarrays, and Series differently from any other Python object. Namely, these types will be evaluated element-by-element whereas every other Python object will be evaluated as a whole against each element of the caller.

[cmp0xff]

288f06e does it look better?

[rhshadrach]

@cmp0xff - see #62063 (comment)

[cmp0xff]

@cmp0xff - see #62063 (comment)

Hi, I adapted the new idea and added a test.