[docs] Profile objects should be documented (issue 6696)

[thomaspinckney3 at gmail.com]

I made some changes based on your comments and will be uploading a new
patch in a couple of minutes.


http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst
File Doc/library/profile.rst (left):

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#oldcode10
Doc/library/profile.rst:10: :synopsis: Python source profiler.
I moved it down to where the .. module definition for cProfile and the
actual module interface definition is. I suppose I could move them both
to the top, but seemed more helpful to jump people straight to the
actual API instead of the pre-amble if someone is clicking into this.

On 2013/04/04 02:26:18, ezio.melotti wrote:
> Why have you removed these?

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#oldcode10
Doc/library/profile.rst:10: :synopsis: Python source profiler.
On 2013/04/04 02:26:18, ezio.melotti wrote:
> Why have you removed these?

Done.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst
File Doc/library/profile.rst (right):

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode8
Doc/library/profile.rst:8: :source:`Modules/_lsprof.c` and
:source:`Lib/pstats.py`
Seems helpful to list ALL the source code instead of just some of it,
no? Or is there a convention about not doing this?

On 2013/04/04 02:26:18, ezio.melotti wrote:
> :source:`Lib/cProfile.py` and :source:`Modules/_lsprof.c` shouldn't be
included
> IMHO.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode8
Doc/library/profile.rst:8: :source:`Modules/_lsprof.c` and
:source:`Lib/pstats.py`
On 2013/04/04 02:26:18, ezio.melotti wrote:
> :source:`Lib/cProfile.py` and :source:`Modules/_lsprof.c` shouldn't be
included
> IMHO.

Done.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode63
Doc/library/profile.rst:63: cProfile.run('foo(x)')
This was addressing a specific confusion one of our developers had. They
wanted to profile a function that took parameters and they weren't
immediately clear on how to do it.

On 2013/04/04 02:26:18, ezio.melotti wrote:
> Why this change?
> It seems easier to me to say that if you want to profile the function
foo you
> can call .run('foo()').

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode63
Doc/library/profile.rst:63: cProfile.run('foo(x)')
On 2013/04/04 02:26:18, ezio.melotti wrote:
> Why this change?
> It seems easier to me to say that if you want to profile the function
foo you
> can call .run('foo()').

Done.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode77
Doc/library/profile.rst:77: 43/3    0.533    0.012    0.749    0.250
pobject.py:99(evaluate)
Great suggestion. I will use your re.compile example.

On 2013/04/04 02:26:18, ezio.melotti wrote:
> I think it would be even better to use a real-world example that users
can run
> (maybe you can thing about something better than re.compile), e.g.:
> >>> import cProfile
> >>> import re
> >>> cProfile.run('re.compile("foo|bar")')
>          197 function calls (192 primitive calls) in 0.002 seconds
> 
>    Ordered by: standard name
> 
>    ncalls  tottime  percall  cumtime  percall
filename:lineno(function)
>         1    0.000    0.000    0.001    0.001 <string>:1(<module>)
>         1    0.000    0.000    0.001    0.001 re.py:212(compile)
>         1    0.000    0.000    0.001    0.001 re.py:268(_compile)
>         1    0.000    0.000    0.000    0.000
> sre_compile.py:172(_compile_charset)
>         1    0.000    0.000    0.000    0.000
> sre_compile.py:201(_optimize_charset)
>         4    0.000    0.000    0.000    0.000
> sre_compile.py:25(_identityfunction)
>       3/1    0.000    0.000    0.000    0.000
sre_compile.py:33(_compile)

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode77
Doc/library/profile.rst:77: 43/3    0.533    0.012    0.749    0.250
pobject.py:99(evaluate)
On 2013/04/04 02:26:18, ezio.melotti wrote:
> I think it would be even better to use a real-world example that users
can run
> (maybe you can thing about something better than re.compile), e.g.:
> >>> import cProfile
> >>> import re
> >>> cProfile.run('re.compile("foo|bar")')
>          197 function calls (192 primitive calls) in 0.002 seconds
> 
>    Ordered by: standard name
> 
>    ncalls  tottime  percall  cumtime  percall
filename:lineno(function)
>         1    0.000    0.000    0.001    0.001 <string>:1(<module>)
>         1    0.000    0.000    0.001    0.001 re.py:212(compile)
>         1    0.000    0.000    0.001    0.001 re.py:268(_compile)
>         1    0.000    0.000    0.000    0.000
> sre_compile.py:172(_compile_charset)
>         1    0.000    0.000    0.000    0.000
> sre_compile.py:201(_optimize_charset)
>         4    0.000    0.000    0.000    0.000
> sre_compile.py:25(_identityfunction)
>       3/1    0.000    0.000    0.000    0.000
sre_compile.py:33(_compile)

Done.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode104
Doc/library/profile.rst:104: provides the respective data of each
function
Trailing comma removed. The trailing full stop under cumtime is kind of
strange to remove since it does really end a full sentence. But happy to
remove it if that what the style guidelines say to do.

On 2013/04/04 02:26:18, ezio.melotti wrote:
> The end of lines are inconsistent.  You can remove the trailing commas
and full
> stop.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode104
Doc/library/profile.rst:104: provides the respective data of each
function
On 2013/04/04 02:26:18, ezio.melotti wrote:
> The end of lines are inconsistent.  You can remove the trailing commas
and full
> stop.

Done.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode280
Doc/library/profile.rst:280: Profile the cmd via :func:`exec` with the
specified global and local environment.
Fixed. I reformatted some of the other paragraphs to make them fill out
to 80 chars too.

On 2013/04/04 02:26:18, ezio.melotti wrote:
> Line too long (there are a few others that are longer than 80 chars
too).

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode280
Doc/library/profile.rst:280: Profile the cmd via :func:`exec` with the
specified global and local environment.
On 2013/04/04 02:26:18, ezio.melotti wrote:
> Line too long (there are a few others that are longer than 80 chars
too).

Done.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode397
Doc/library/profile.rst:397: +------------------+----------------------+
This was from the prior author and I just didn't feel like reformatting
it all. Maybe in the next patch :)

On 2013/04/04 02:26:18, ezio.melotti wrote:
> Here you could use the simpler table syntax:
> ====== ======
> header header
> ====== ======
> row1   row1
> row2   row2
> ...    ...
> ====== ======

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode397
Doc/library/profile.rst:397: +------------------+----------------------+
On 2013/04/04 02:26:18, ezio.melotti wrote:
> Here you could use the simpler table syntax:
> ====== ======
> header header
> ====== ======
> row1   row1
> row2   row2
> ...    ...
> ====== ======

Done.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode418
Doc/library/profile.rst:418: .. For compatibility with the old profiler,
command executed!

On 2013/04/04 02:26:18, ezio.melotti wrote:
> s/,/./

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode418
Doc/library/profile.rst:418: .. For compatibility with the old profiler,
On 2013/04/04 02:26:18, ezio.melotti wrote:
> s/,/./

Done.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode447
Doc/library/profile.rst:447: printed; as of Python 1.5b1, this uses the
Perl-style regular
Removed.

On 2013/04/04 02:26:18, ezio.melotti wrote:
> This can probably be removed.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode447
Doc/library/profile.rst:447: printed; as of Python 1.5b1, this uses the
Perl-style regular
On 2013/04/04 02:26:18, ezio.melotti wrote:
> This can probably be removed.

Done.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode618
Doc/library/profile.rst:618: interpreted differently:
I do mention the new python 3 time functions, but I don't have enough
first hand experience with doing this to know what the best
recommendation is.

On 2013/04/04 02:26:18, ezio.melotti wrote:
> This could point to the different times available in the time module,
and
> possibly provide some suggestion.

http://bugs.python.org/review/6696/diff/7348/Doc/library/profile.rst#newcode618
Doc/library/profile.rst:618: interpreted differently:
On 2013/04/04 02:26:18, ezio.melotti wrote:
> This could point to the different times available in the time module,
and
> possibly provide some suggestion.

Done.

http://bugs.python.org/review/6696/