DOC: Inconsistent and incomplete documentation of `pandas.eval`

[domsmrz]

Pandas version checks

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

Location of the documentation

1. https://pandas.pydata.org/docs/reference/api/pandas.eval.html
2. https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.eval.html
3. https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.query.html

Documentation problem

• (1) doesn't cover all supported operators within the expr string, e.g., < or sin e.t.c.,
• (2) doesn't explain how expr should look like. Admittedly it links to (1) but only in kwargs section.
• (3) doesn't explain how expr should look like, albeit it explains how to use columns within the expr. Admittedly it links to (1) but only in kwargs section.

Suggested fix for documentation

• Expand (1) to cover all supported operators and functions
• To expr sections of (2) and (3) add links leading to (1) for description of expr
• Move description of expr from (3) to (2) and add another link to that section leading to (2) (to explain how one can use columns)
  • Alternatively just add link to expr section of (2) leading to (3) (to explain columns) instead. Albeit personally i feel it is easier to have the eval as main source and query link there as query is equivalent of df[df.eval(...)]

[rhshadrach]

Thanks for the suggestions - agreed this could be improved. +1 on all counts, and I too would prefer not doing your alternative suggestion.

[droussea2001]

take

[JonathanMarriott]

@droussea2001 are you still working on this? If not I am happy to take it

[droussea2001]

Hello @JonathanMarriott : no you can take it :-)

[JonathanMarriott]

take