[Python-ideas] api suggestions for the cProfile module

[Thane Brimhall]

I use cProfile a lot, and would like to suggest three backwards-compatible
improvements to the API.

1: When using cProfile on a specific piece of code I often use the enable()
and disable() methods. It occurred to me that this would be an obvious
place to use a context manager.

2: Enhance the `print_stats` method on Profile to accept more options
currently available only through the pstats.Stats class. For example,
strip_dirs could be a boolean argument, and limit could accept an int. This
would reduce the number of cases you'd need to use the more complex API.

3: I often forget which string keys are available for sorting. It would be
nice to add an enum for these so a user could have their linter and IDE
check that value pre-runtime. Since it would subclass `str` and `Enum` it
would still work with all currently existing code.

The current documentation contains the following code:

import cProfile, pstats, io
pr = cProfile.Profile()
pr.enable()
# ... do something ...
pr.disable()
s = io.StringIO()
sortby = 'cumulative'
ps = pstats.Stats(pr, stream=s).sort_stats(sortby)
ps.print_stats()
print(s.getvalue())

While the code below doesn't exactly match the functionality above (eg. not
using StringIO), I envision the context manager working like this, along
with some adjustments on how to get the stats from the profiler:

import cProfile, pstats
with cProfile.Profile() as pr:
    # ... do something ...
    pr.print_stats(sort=pstats.Sort.cumulative, limit=10, strip_dirs=True)

As you can see, the code is shorter and somewhat more self-documenting. The
best thing about these suggestions is that as far as I can tell they would
be backwards-compatible API additions.

What do you think? Thank you in advance for your time!

/Thane
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20161220/615d4a06/attachment.html>