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

pstats.Stats.print_callers と print_callees から始め、提案されているキーワード引数と、並べ替えおよびフィルタリングの共通動作を、リンク先の PR gh-125856 と比較します。呼び出し元と呼び出し先の詳細を、説明どおり独立して並べ替え、件数を制限でき、既存のトップレベルのフィルタリング動作が維持されていれば完了です。