pstats.Stats: Add caller/callee sorting and filtering options to `print_callers` and `print_callees`

Feature or enhancement

Proposal:

Currently: print_callers(*amount) only applies its provided filters to the top-level details (the callees for print_callers and callers for print_callees), and the second-level details are unfiltered and left sorted by name. If you want to print the top 20 callers of a function with 1000 callers and you run print_callers(funcname, 20), you will get the top 20 matches of funcname and each will have all 1000 callers. Hence, the nominal workflow to sort and limit the number of callers for a particular function is to print the results, copy them (or read them back in from a file), parse them by splitting on whitespace and casting to ints and floats, and then sort.

I'm proposing (with a PR to follow) adding new keyword arguments as shown below, that are explicitly used for sorting and limiting the callers/callees, refactoring parts of the Stats class to share the sorting and filtering code.

    def print_callees(self, *amount, callees_sort_key=None, callees_filter=()):
        [...]

    def print_callers(self, *amount, callers_sort_key=None, callers_filter=()):
        [...]

Example:

>>> 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>

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

Feature proposal: https://discuss.python.org/t/pstats-stats-objects-should-allow-sorting-caller-callee-stats/67892

A previous stackoverflow question from someone else with a similar need: python - Why is pstats.print_callers() ignores the restriction argument? - Stack Overflow

Linked PRs

• gh-125856

Start with pstats.Stats.print_callers and print_callees, then compare the proposed keyword arguments and shared sorting/filtering behavior with linked PR gh-125856. Done means caller and callee details can be independently sorted and limited as described, while preserving the existing top-level filtering behavior.