Re: [PATCH v2 57/58] perf Documentation: Update for standalone Python scripts and remove obsolete data

sashiko-bot
2026-04-23T05:31:36Z

Sashiko AI review found 2 potential issue(s):
- [Medium] Incorrect Python API documentation for perf.data.__init__ causing runtime errors
- [Low] Obsolete reference to 'report mode' in --show-info documentation
--

commit c8608ebf0770d6f59d09319da7fc7cb3688932bb
Author: Ian Rogers <irogers@google.com>

perf Documentation: Update for standalone Python scripts and remove obsolete data

This commit removes obsolete perf script documentation for Perl and older Python
modes, and updates the Python documentation to reflect the new standalone
script usage with the perf module.

> diff --git a/tools/perf/Documentation/perf-script-python.txt b/tools/perf/Documentation/perf-script-python.txt
> index 27a1cac6fe763..9293057cee8e2 100644
> --- a/tools/perf/Documentation/perf-script-python.txt
> +++ b/tools/perf/Documentation/perf-script-python.txt

[ ... ]

> +### `perf.data`
>
> -ev_name, comm, id, stream_id, pid, tid, cpu, ip, time, period, phys_addr,
> -addr, symbol, symoff, dso, time_enabled, time_running, values, callchain,
> -brstack, brstacksym, datasrc, datasrc_decode, iregs, uregs,
> -weight, transaction, raw_buf, attr, cpumode.
> +Represents a trace file.
>
> -Fields that may also be present:
> -
> - flags - sample flags
> - flags_disp - sample flags display
> - insn_cnt - instruction count for determining instructions-per-cycle (IPC)
> - cyc_cnt - cycle count for determining IPC
> - addr_correlates_sym - addr can correlate to a symbol
> - addr_dso - addr dso
> - addr_symbol - addr symbol
> - addr_symoff - addr symbol offset
> +- `__init__(filename, mode=perf.DATA_MODE_READ)`: Opens a trace file.

Is the signature __init__(filename, mode=perf.DATA_MODE_READ) consistent
with the underlying C extension implementation?

Looking at pyrf_data__init in python.c, it appears to use
PyArg_ParseTupleAndKeywords with the keyword list {"path", "fd", NULL} and
hardcodes the internal mode to PERF_DATA_MODE_READ.

It also seems DATA_MODE_READ is not exported as a constant to Python in the
perf__constants array. Additionally, the .pyi stubs specify
def __init__(self, path: str = ..., fd: int = ...).

If a user follows this documentation and passes mode=perf.DATA_MODE_READ,
will their script crash with an AttributeError for the missing constant and a
TypeError for the invalid keyword argument?

[ ... ]

> diff --git a/tools/perf/Documentation/perf-script.txt b/tools/perf/Documentation/perf-script.txt
> index 200ea25891d88..93ed1ea704c95 100644
> --- a/tools/perf/Documentation/perf-script.txt
> +++ b/tools/perf/Documentation/perf-script.txt

[ ... ]

> @@ -23,52 +20,9 @@ There are several variants of perf script:
> 'perf script' to see a detailed trace of the workload that was
> recorded.
>
> - You can also run a set of pre-canned scripts that aggregate and
> - summarize the raw trace data in various ways (the list of scripts is
> - available via 'perf script -l'). The following variants allow you to
> - record and run those scripts:
> -
> - 'perf script record <command>' to record the events required
> - for 'perf script report'. is the name displayed in the
> - output of 'perf script --list' i.e. the actual script name minus any
> - language extension. If <command> is not specified, the events are
> - recorded using the -a (system-wide) 'perf record' option.
> -
> - 'perf script report [args]' to run and display the results

Since the perf script report functionality is removed here, should the
documentation for the --show-info option also be updated?

Further down in this file, the documentation for --show-info currently
states: "It can only be used with the perf script report mode."

As this mode no longer exists and the option functions independently in the
C implementation, does leaving this text mislead users into thinking the
option is tied to a deprecated mode?

> - of . is the name displayed in the output of 'perf
> - script --list' i.e. the actual script name minus any language
> - extension. The perf.data output from a previous run of 'perf script

--
Sashiko AI review · https://sashiko.dev/#/patchset/20260423035526.1537178-1-irogers@google.com?part=57