https://github.com/python/cpython/commit/ef3b8829e434b16f136d55cae8b9853cac113f01
commit: ef3b8829e434b16f136d55cae8b9853cac113f01
branch: main
author: László Kiss Kollár <[email protected]>
committer: pablogsal <[email protected]>
date: 2026-01-03T21:16:29Z
summary:
gh-142927: Clarify pstats file output in docs and CLI (#143388)
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.
files:
M Doc/library/profiling.sampling.rst
M Lib/profiling/sampling/cli.py
diff --git a/Doc/library/profiling.sampling.rst
b/Doc/library/profiling.sampling.rst
index 9bc58b4d1bc976..4ec594c041d3f5 100644
--- a/Doc/library/profiling.sampling.rst
+++ b/Doc/library/profiling.sampling.rst
@@ -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
diff --git a/Lib/profiling/sampling/cli.py b/Lib/profiling/sampling/cli.py
index c0dcda46fc29d3..f4b31aad45b922 100644
--- a/Lib/profiling/sampling/cli.py
+++ b/Lib/profiling/sampling/cli.py
@@ -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",
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
