gh-125855: pstats.Stats: Allow sorting/filtering by caller/callee

[Zannick]

This PR adds new keyword arguments callers_sort_key and callers_filter to pstats.Stats.print_callers, and similar to pstats.Stats.print_callees, and documents them in the profiling doc. The sorting and filtering are accomplished via use of similar code in pstats.Stats, now refactored to be shared, though unlike sort_stats the sorting is not sticky.

This produces something like:

>>> p.print_callers(r'\(has\)', callers_sort_key='time', callers_filter=5)
   Ordered by: internal time
   List reduced from 965 to 1 due to restriction <'\\(has\\)'>

   Callers ordered by: internal time

Function                 was called by...
                             ncalls  tottime  cumtime
BaseClasses.py:820(has)  <-    4926    0.002    0.002  worlds\overcooked2\Logic.py:6(has_requirements_for_level_access)
                               1148    0.000    0.001  worlds\overcooked2\Logic.py:291(can_reach_sky_shelf)
                               1119    0.000    0.000  worlds\overcooked2\Logic.py:278(can_reach_stonehenge_mountain)
                                728    0.000    0.000  worlds\overcooked2\Logic.py:257(can_reach_yellow_island)
                                220    0.000    0.000  worlds\overcooked2\Logic.py:310(can_reach_pink_island)
   List reduced from 7 to 5 due to restriction <5>

---

📚 Documentation preview 📚: https://cpython-previews--125856.org.readthedocs.build/

• Issue: pstats.Stats: Add caller/callee sorting and filtering options to print_callers and print_callees #125855

[ghost]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[rruuaanng]

Does it have to be preceded by a space?

print(f"Callers ordered by: {sort_type}")

(print default line break)

[Zannick]

1. Yes, it matches indentation with the lines printed before it. See below.

2. I prefer f-strings but thought it would be better to follow existing style. Should I use f-strings anyway?

3. Existing output style puts a blank line before the call heading below, like:

      Ordered by: internal time
      List reduced from 965 to 1 due to restriction <'\\(has\\)'>
   
      Callers ordered by: internal time
   
   Function    was called by...
   [...]
   

   I can replace the '\n' with a print() if that is better?

   The blank line before "Callers" I would like to remove but that would require more mostly-unrelated changes.

[Zannick]

Any opinion on my changes to this?

[ZeroIntensity]

@Zannick Please don't force push, it makes reviewing much more difficult. Everything is squash merged at the end.

[Zannick]

@Zannick Please don't force push, it makes reviewing much more difficult. Everything is squash merged at the end.

Sorry, thought it would be okay to amend a whitespace issue out of the last commit within a few minutes. Bad habit, I admit.