# scope_profiler.inspection

*module*

CLI entry point for ``scope-profiler inspect``: summarize a profiling file.

Prints the run metadata in full and a one-line-per-region overview of the
timing data, plus a LIKWID hardware-counter table per rank and event group
when the run recorded any, without producing any plots. The metadata can
also be exported to JSON, either from the CLI (``--export-metadata``) or
with :func:`write_metadata_json`.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/inspection.py#L1-L1)

## scope_profiler.inspection.build_parser

*function*

```python
def build_parser() -> argparse.ArgumentParser
```

Build the argument parser for ``scope-profiler inspect``.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/inspection.py#L375-L455)

## scope_profiler.inspection.collect_file_metadata

*function*

```python
def collect_file_metadata(profiling_data: ProfilingResults | str | Path | Sequence) -> dict
```

Collect the run metadata of one or more profiling files.

Parameters
----------
profiling_data : ProfilingResults, path, or sequence of either
    Files to read the metadata from.

Returns
-------
dict
    ``{"files": [{"file_path": ..., "num_ranks": ..., "metadata": {...}}]}``,
    matching the envelope used by
    :func:`~scope_profiler.plotting_scripts.collect_region_statistics`, so
    a single document can describe several runs.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/inspection.py#L301-L343)

## scope_profiler.inspection.inspect_file

*function*

```python
def inspect_file(file_path, include=None, exclude=None, ranks=None, sort: str = 'start', show_metadata: bool = True, show_regions: bool = True, full: bool = False, source: list | None = None, columns=None, percentage_mode: str = 'coverage', stream=None) -> None
```

Print a summary of one profiling HDF5 file.

Parameters
----------
file_path : str or Path
    Merged profiling file to inspect.
include, exclude : list of str or str, optional
    Regex patterns selecting which regions to report.
ranks : list of int, optional
    Restrict the region statistics to these ranks (default: all).
sort : str, optional
    Region ordering: one of ``total``, ``calls``, ``avg``, ``max`` (all
    descending) or ``name`` (alphabetical). Default: ``total``.
show_metadata, show_regions : bool, optional
    Sections to print (both default to True).
full : bool, optional
    Print long metadata values in full instead of clipping them.
source : list of str, optional
    Region names to print the captured call-site source of (the ``with``
    block or decorated function that defines each region - see
    ``ProfileManager.profile_region`` and issue #161). Printed after the
    region table, regardless of ``include``/``exclude``.
columns : list of str or str, optional
    Region summary columns to print. Defaults to ``region``, ``calls``,
    ``percent``, ``total`` and ``avg``.
percentage_mode : {"coverage", "exclusive"}, optional
    Quantity used for ``% session``. Defaults to wall-clock coverage.
stream : file-like, optional
    Where to write (default: stdout).

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/inspection.py#L167-L281)

## scope_profiler.inspection.main

*function*

```python
def main(argv: list | None = None)
```

Entry point for ``scope-profiler inspect``.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/inspection.py#L458-L493)

## scope_profiler.inspection.write_metadata_json

*function*

```python
def write_metadata_json(profiling_data: ProfilingResults | str | Path | Sequence, filepath: str | Path) -> dict
```

Write the run metadata of one or more profiling files to JSON.

Parameters
----------
profiling_data : ProfilingResults, path, or sequence of either
    Files to read the metadata from.
filepath : str or Path
    Destination JSON file. Parent directories are created as needed.

Returns
-------
dict
    The payload that was written (see :func:`collect_file_metadata`).

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/inspection.py#L346-L372)