From ed314a303daaaae35affdfb8d10930d7bc7fc5c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A1szl=C3=B3=20Kiss=20Koll=C3=A1r?= Date: Sat, 3 Jan 2026 10:59:51 +0000 Subject: [PATCH] Clarify pstats file output in docs and CLI 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. --- Doc/library/profiling.sampling.rst | 13 ++++++++----- Lib/profiling/sampling/cli.py | 4 ++-- 2 files changed, 10 insertions(+), 7 deletions(-) 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 , --output Output file or directory path. Default behavior varies by format: - :option:`--pstats` writes to stdout, while other formats generate a file - named ``_.`` (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 + ``_.`` (for example, ``flamegraph_12345.html``). :option:`--heatmap` creates a directory named ``heatmap_``. .. 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",