Re: [PATCH v1 22/58] perf python: Add perf.pyi stubs file

sashiko-bot
2026-04-20T00:33:22Z

Sashiko AI review found 3 potential issue(s):
- [Medium] The `perf.pyi` type stub provides incorrect attribute names that will cause runtime crashes.
- [Medium] The `perf.pyi` stub file is not installed by the build system.
- [Medium] The `perf.pyi` type stubs omit several functions and classes exported by the C extension.
--

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

perf python: Add perf.pyi stubs file

This commit adds Python type stubs (perf.pyi) for the perf module to
improve editor support and static analysis. It includes docstrings for
classes, methods, and constants derived from the python extension.

> diff --git a/tools/perf/python/perf.pyi b/tools/perf/python/perf.pyi
> new file mode 100644
> index 0000000000000..0aa897f453153
> --- /dev/null
> +++ b/tools/perf/python/perf.pyi

Looking at tools/perf/util/setup.py and tools/perf/Makefile.perf,
it appears only .py files are copied during installation.

Is this a regression where the build system leaves the .pyi file
behind in the source tree, making it inaccessible to the user's
Python environment?

[ ... ]

> +def parse_events(
> + event_string: str,
> + cpus: Optional[cpu_map] = None,
> + threads: Optional[Any] = None
> +) -> 'evlist':

Functions like parse_metrics, pmus, and tracepoint appear to be absent
from these stubs.

Could this regression cause static analyzers to flag valid uses of the
interface because module-level functions exported by the python
extension are missing?

[ ... ]

> +class evsel:
> + """Event selector, represents a single event being monitored."""
> + def __str__(self) -> str:

Instantiable classes like evsel and evlist appear to be missing their
constructors in the stubs.

Is it a regression that this class does not include its __init__ method?

[ ... ]

> +class sample_event:
> + """Represents a sample event from perf."""
> + evsel: evsel
> + sample_cpu: int
> + sample_time: int
> + sample_pid: int
> + sample_comm: str

Looking at pyrf_sample_event__members in tools/perf/util/python.c,
sample_comm does not appear to be exported.

Could this regression pass static analysis but fail with an
AttributeError at runtime if developers use event.sample_comm?

[ ... ]

> +class branch_entry:
> + """Represents a branch entry in the branch stack.
> +
> + Attributes:
> + from_: Source address of the branch (corresponds to 'from' keyword).
> + to: Destination address of the branch.

[ ... ]

> + from_: int
> + to: int

The python extension explicitly exports this branch entry attribute as
"from" via pyrf_branch_entry__getset.

Since "from" is a Python keyword, it is typically accessed via
getattr(entry, 'from').

Would defining it as from_ be a regression that leads to an
AttributeError at runtime?

[ ... ]

> +class evlist:
> + def open(self) -> None:
> + """Open the events in the list."""
> + ...

The stubs omit several event classes entirely, such as mmap_event,
lost_event, comm_event, task_event, throttle_event, read_event, and
switch_event.

Is it a regression that methods like get_pollfd and add are also missing
from evlist?

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