classification
Title: Profile objects should be documented
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: amyodov, asvetlov, docs@python, eric.araujo, ezio.melotti, georg.brandl, gvanrossum, python-dev, terry.reedy, thomaspinckney3
Priority: high Keywords: patch

Created on 2009-08-13 16:57 by amyodov, last changed 2013-04-13 01:19 by thomaspinckney3. This issue is now closed.

Files
File name Uploaded Description Edit
patch.diff thomaspinckney3, 2012-05-12 22:25 edits to profiler docs review
patch2.diff thomaspinckney3, 2013-02-10 23:35 second draft of edits to profiler docs review
patch3.diff thomaspinckney3, 2013-04-05 19:03 review
patch4.diff thomaspinckney3, 2013-04-09 22:01 review
Messages (21)
msg91522 - (view) Author: Alexander Myodov (amyodov) Date: 2009-08-13 16:57
Seems like a minor documentation issue in 2.x became more significant 
one in 3.x.

In Python 2.6 (and lower), the documentation on Profile objects 
discussed them as a part of hotshot module, while omitting the fact 
that any profiler module, either of profile/cProfile/hotshot, supports 
them (though in fact, hotshot Profile objects have an api a bit 
different from profile/cProfile Profile objects). Note http://
docs.python.org/2.6/library/hotshot.html#profile-objects - there is no 
separate documentation of non-hotshot Profile objects, though they are 
largely similar. This is a minor issue which could probably be fixed in 
2.7 as a separate problem - otherwise it is pretty unclear from the 
documentation, what methods do cProfile Profile objects support (eg, 
they support enable()/disable() and runcall() methods, which is pretty 
useful for profiling, but impossible to find in documentation).

In Python 3.1, looks like everything related to hotshot was removed 
from the documents, including the documentation on Profile objects - 
which should not have been. This means, that now the documentation on 
profilers does not cover any Profile classes at all - see http://
docs.python.org/3.1/library/profile.html . For example, the official 
documentation doesn't say any way to profile a function passing 
arguments to it and receiving its result - while profile/cProfile 
Profile objects still do support runcall() method.
msg113015 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-05 19:07
I am just responding so this will not show up on the 'unanswered issues' list. It appears that GB has accepted this as something that needs to be done.
msg160356 - (view) Author: Tom Pinckney (thomaspinckney3) * Date: 2012-05-10 18:11
Looking at the current docs for 3.3, it looks like there are a bunch of other ways that the docs could be clarified:

1) Proper documentation of the complete profile.Profile() and cProfile.Profile() interfaces. 

2) Adding other examples to the quick start section at the top for how to process the resulting stats without printing them to stdout or writing them to a file.

I'll take a stab at this.
msg160498 - (view) Author: Tom Pinckney (thomaspinckney3) * Date: 2012-05-12 22:25
I took a stab at updating the docs based on the current profiler source. See attached patch for a first draft. 

This is my first doc patch so would appreciate any feedback on style and substance of my changes.

I tried to document more of the modules (for example the internal Profile object), logically arrange things a better better IMHO, and generally be more precise about what is happening.
msg181402 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2013-02-05 00:53
Can someone review Thomas's patch?  It's nearly a year old...  I just discovered this same issue.
msg181404 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-02-05 02:51
I learned a lot of that stuff recently thanks to a tutorial from Greg Ward.  Reviewing the patch now.
msg181407 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-02-05 03:06
Tom, I’m sory your contribution was ignored, and I hope you still get Python bugs email.  The patch is great.  I made comments about contents and form on the code review site; you can follow the “review” link in the list of files on the top of this page if you didn’t get an email from the review app.
msg181417 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2013-02-05 04:07
Eric, you could also check it in with your own changes added.

How far can we backport docs?
msg181418 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-02-05 04:23
2.7 and 3.2.

I’ll wait a few days to let Thomas get the email and reply if he wants.
msg181436 - (view) Author: Tom Pinckney (thomaspinckney3) * Date: 2013-02-05 13:38
Thanks for the feedback!

I'll incorporate it this weekend and make a new patch, though also feel free to just go ahead and make the changes yourself if you'd rather not wait for me.
msg181452 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-02-05 16:20
There is no rush, even if this doesn’t get into the docs distributed with the releases that are due next week-end, people will see it in the online docs a day after it’s committed.
msg181862 - (view) Author: Tom Pinckney (thomaspinckney3) * Date: 2013-02-10 23:35
Draft of new updates based on Eric's feedback. I haven't done a final proof-reading over this patch as I wanted to upload it and see if I'm heading in the right direction first.
msg185658 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-03-31 19:57
Ezio, would you like to commit this?
msg186100 - (view) Author: Tom Pinckney (thomaspinckney3) * Date: 2013-04-05 19:03
Updated based on Ezio's comments.
msg186456 - (view) Author: Tom Pinckney (thomaspinckney3) * Date: 2013-04-09 22:01
Another update based on comments. Removed links to cProfile.py and _lsof.c.
msg186520 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-04-10 17:06
Last patch LGTM (except a couple of minor whitespace issues).
Tom, can you sign the contributor agreement (http://www.python.org/psf/contrib/contrib-form/)?
msg186538 - (view) Author: Tom Pinckney (thomaspinckney3) * Date: 2013-04-11 01:42
Great!

Just signed the contributor agreement.

On Apr 10, 2013, at 1:06 PM, Ezio Melotti <report@bugs.python.org> wrote:

> 
> Ezio Melotti added the comment:
> 
> Last patch LGTM (except a couple of minor whitespace issues).
> Tom, can you sign the contributor agreement (http://www.python.org/psf/contrib/contrib-form/)?
> 
> ----------
> stage: patch review -> commit review
> versions:  -Python 3.2
> 
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue6696>
> _______________________________________
msg186623 - (view) Author: Roundup Robot (python-dev) Date: 2013-04-12 13:25
New changeset cd785c9d26c2 by Ezio Melotti in branch '3.3':
#6696: add documentation for the Profile objects, and improve profile/cProfile docs.  Patch by Tom Pinckney.
http://hg.python.org/cpython/rev/cd785c9d26c2

New changeset 81dabc1feb52 by Ezio Melotti in branch 'default':
#6696: merge with 3.3.
http://hg.python.org/cpython/rev/81dabc1feb52

New changeset b57245574717 by Ezio Melotti in branch '2.7':
#6696: add documentation for the Profile objects, and improve profile/cProfile docs.  Patch by Tom Pinckney.
http://hg.python.org/cpython/rev/b57245574717
msg186624 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-04-12 13:26
Fixed, thanks for the patch!
msg186625 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2013-04-12 13:31
Cool! Thanks.
msg186686 - (view) Author: Tom Pinckney (thomaspinckney3) * Date: 2013-04-13 01:19
Thanks everyone for helping me through my first python patch submission.
History
Date User Action Args
2013-04-13 01:19:21thomaspinckney3setmessages: + msg186686
2013-04-12 13:31:45asvetlovsetmessages: + msg186625
2013-04-12 13:26:55ezio.melottisetstatus: open -> closed
type: behavior -> enhancement
messages: + msg186624

assignee: eric.araujo -> ezio.melotti
resolution: fixed
stage: commit review -> resolved
2013-04-12 13:25:57python-devsetnosy: + python-dev
messages: + msg186623
2013-04-11 01:42:19thomaspinckney3setmessages: + msg186538
2013-04-10 17:06:37ezio.melottisetstage: patch review -> commit review
messages: + msg186520
versions: - Python 3.2
2013-04-09 22:01:17thomaspinckney3setfiles: + patch4.diff

messages: + msg186456
2013-04-05 19:03:07thomaspinckney3setfiles: + patch3.diff

messages: + msg186100
2013-03-31 19:57:14eric.araujosetnosy: + ezio.melotti
messages: + msg185658
2013-02-10 23:35:15thomaspinckney3setfiles: + patch2.diff

messages: + msg181862
2013-02-05 16:20:37eric.araujosetassignee: docs@python -> eric.araujo
messages: + msg181452
2013-02-05 13:38:36thomaspinckney3setmessages: + msg181436
2013-02-05 04:23:44eric.araujosetmessages: + msg181418
2013-02-05 04:07:21gvanrossumsetmessages: + msg181417
2013-02-05 03:06:22eric.araujosetmessages: + msg181407
2013-02-05 02:51:00eric.araujosetstage: needs patch -> patch review
messages: + msg181404
versions: + Python 3.4
2013-02-05 00:53:23gvanrossumsetnosy: + gvanrossum
messages: + msg181402
2012-08-16 21:07:34asvetlovsetnosy: + asvetlov
2012-05-12 22:25:37thomaspinckney3setfiles: + patch.diff
keywords: + patch
messages: + msg160498
2012-05-10 23:42:05eric.araujosetnosy: + eric.araujo

versions: + Python 2.7
2012-05-10 18:11:22thomaspinckney3setnosy: + thomaspinckney3
messages: + msg160356
2011-06-12 21:30:31terry.reedysetversions: + Python 3.3, - Python 3.1
2010-12-14 01:56:56r.david.murraysetstage: needs patch
type: behavior
versions: + Python 3.2
2010-08-05 19:07:55terry.reedysetnosy: + terry.reedy
messages: + msg113015
2010-08-02 20:57:57georg.brandlsetpriority: normal -> high
2010-08-01 11:39:45BreamoreBoysetassignee: georg.brandl -> docs@python

nosy: + docs@python
2009-08-13 16:57:15amyodovcreate