classification
Title: profile.Profile() has no method enable()
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: bbayles, cheryl.sabella, docs@python, eric.araujo, ezio.melotti, pitrou, willingc
Priority: normal Keywords: patch

Created on 2017-11-13 21:17 by pitrou, last changed 2018-02-25 15:27 by bbayles.

Pull Requests
URL Status Linked Edit
PR 5887 open bbayles, 2018-02-25 15:23
Messages (5)
msg306169 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2017-11-13 21:17
The section here is wrong as it claims that API is common to profile and cProfile.

https://docs.python.org/3/library/profile.html#module-cProfile
msg312448 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python triager) Date: 2018-02-21 00:46
I started taking a look at this and discovered a few things.  There are four methods in the C module `_lsprof` that are within the Profiler class - `enable`, `disable`, `getstats`, and `clear` and which are all available through cProfile.Profile.  These aren't available in profile.py.  Also, `getstats` and `clear` aren't in the documentation and `enable` takes two optional parameters that aren't mentioned in the documentation.  There are also many methods in profile.py that aren't documented.

What would be the preferred approach to fixing the documentation?  It seems that the documentation currently focuses on trying to make profile and cProfile as similar as possible.  Should they have separate sections that define the differences?  Or should `enable` and `disable` be removed since they aren't in profile?  The example under https://docs.python.org/3.8/library/profile.html#profile.Profile  uses `enable` and `disable` and seems to be a helpful example.
msg312486 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2018-02-21 10:17
We can't remove public-looking methods (i.e. they don't start with an underscore) like that because some people may be using them.  Rather than document the differences, I think it would be more useful to try to bridge the gap by augmenting the profile API with whatever supplementary APIs cProfile has.  If some API is difficult to implement for profile, then we can revisit that goal and make an exception.
msg312814 - (view) Author: bbayles (bbayles) * Date: 2018-02-25 13:50
I'm afraid that profile.Profile and cProfile.Profile behave pretty differently, and there's not a good way to bring the methods from the C version to the Python version.

The example at [1] shows a cProfile.Profile object being instantiated and enabled. At this point the profiler is tracing execution - until the disable() method is called, any activity is recorded.

profile.Profile doesn't work this way. Creating a profile.Profile object doesn't cause activity to be recorded. It doesn't do anything until you call one of its run* methods.

This is because the C version uses PyEval_SetProfile ([2]) to take advantage of CPython's "low-level support for attaching profiling and execution tracing facilities" ([3]). I don't think we can do that from the Python version.

There is already a precedent for showing differences between cProfile.Profile and profile.Profile in the existing docs - see [4].


[1] https://docs.python.org/3/library/profile.html#profile.Profile
[2] https://github.com/python/cpython/blob/6f0eb93183519024cb360162bdd81b9faec97ba6/Modules/_lsprof.c#L693
[3] https://docs.python.org/3/c-api/init.html#profiling-and-tracing
[4] https://docs.python.org/3/library/profile.html#using-a-custom-timer
msg312818 - (view) Author: bbayles (bbayles) * Date: 2018-02-25 15:27
I've made a pull request that clarifies things in the docs.

As csabella notes, there are some more differences that could be pointed out. The 'subcalls' and 'builtins' arguments could be explained as well.

Nonetheless, I think the PR does fix some definitely incorrect aspects of the existing documentation and is at least an improvement.
History
Date User Action Args
2018-02-25 15:27:59bbaylessetmessages: + msg312818
2018-02-25 15:23:31bbaylessetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request5659
2018-02-25 13:50:57bbaylessetnosy: + bbayles
messages: + msg312814
2018-02-21 10:17:24pitrousetmessages: + msg312486
2018-02-21 00:46:27cheryl.sabellasetversions: + Python 3.8
nosy: + cheryl.sabella

messages: + msg312448

stage: needs patch
2017-11-13 21:17:19pitroucreate