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.

diff --git a/Doc/library/profiling.sampling.rst b/Doc/library/profiling.sampling.rst
index 9bc58b4d1bc9765dfdd270120cced0c393baa2f1..4ec594c041d3f5b34dce04c4a005ed3989d31367 100644 (file)
--- 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 c0dcda46fc29d346af2e08b138d67afc9f1a41bb..f4b31aad45b922fe7f0954c44762513b76465015 100644 (file)
--- 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",