mirror/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-01-26 12:55:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

gh-142927: Clarify pstats file output in docs and CLI (#143388)

Browse Source 
When running the `profiling.sampling` module in pstats mode, the output
can be emitted in two different ways: text to stdout or a binary file
when the `--output` argument is set.

The current documentation and help text is confusing as it does not
distinguish between these two output formats so it may be surprising to
the user to get different formats depending whether `--output` is set or not.
This commit is contained in:
László Kiss Kollár 2026-01-03 21:16:29 +00:00 committed by GitHub
parent 12283f6373
commit ef3b8829e4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 10 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
Doc/library/profiling.sampling.rst
View File

@ -878,9 +878,9 @@ interesting functions that highlights:
Use :option:`--no-summary` to suppress both the legend and summary sections.
To save pstats output to a file instead of stdout::
To save pstats output to a binary file instead of stdout::
python -m profiling.sampling run -o profile.txt script.py
python -m profiling.sampling run -o profile.pstats script.py
The pstats format supports several options for controlling the display.
The :option:`--sort` option determines the column used for ordering results::
@ -1455,7 +1455,9 @@ Output options
.. option:: --pstats
Generate text statistics output. This is the default.
Generate pstats statistics. This is the default.
When written to stdout, the output is a text table; with :option:`-o`,
it is a binary pstats file.
.. option:: --collapsed
@ -1486,8 +1488,9 @@ Output options
.. option:: -o <path>, --output <path>
Output file or directory path. Default behavior varies by format:
:option:`--pstats` writes to stdout, while other formats generate a file
named ``<format>_<PID>.<ext>`` (for example, ``flamegraph_12345.html``).
:option:`--pstats` prints a text table to stdout, while ``-o`` writes a
binary pstats file. Other formats generate a file named
``<format>_<PID>.<ext>`` (for example, ``flamegraph_12345.html``).
:option:`--heatmap` creates a directory named ``heatmap_<PID>``.
.. option:: --browser

4
Lib/profiling/sampling/cli.py
View File

@ -489,8 +489,8 @@ def _add_format_options(parser, include_compression=True, include_binary=True):
"-o",
"--output",
dest="outfile",
help="Output path (default: stdout for pstats, auto-generated for others). "
"For heatmap: directory name (default: heatmap_PID)",
help="Output path (default: stdout for pstats text; with -o, pstats is binary). "
"Auto-generated for other formats. For heatmap: directory name (default: heatmap_PID)",
)
output_group.add_argument(
"--browser",