scope_profiler.json_export

Export and re-read profiling runs as JSON.

The HDF5 file remains the default output: it is compact, appendable rank by rank, and the only format the parallel writer can produce. This module adds a second, dependency-free representation of exactly the same run, for the cases where HDF5 is the wrong shape - a browser, jq, a notebook on a machine without h5py, or a diff in code review.

The document is lossless: :func:read_json rebuilds a :class:~scope_profiler.results.ProfilingResults that is indistinguishable from the one :func:~scope_profiler.h5reader.read_h5 gives back for the same run, per-call timestamps, lane tables, LIKWID counters and line-profiler records included. Timestamps stay in the integer nanoseconds the run recorded rather than being converted to seconds, so a round trip is exact.

Files ending in .gz are written (and read) gzip-compressed, which is what a real run wants: the event columns are the bulk of the document and they compress by roughly an order of magnitude.

Attributes

Name	Description
FORMAT_NAME	No description.
FORMAT_VERSION	No description.
JSON_SUFFIXES	No description.

Classes

Name	Description
JSONProfileError	Raised when a file is not a scope-profiler JSON profile.

Functions

Name	Description
build_json_document	Build the JSON document describing one run.
export_json	Write one JSON document per run, exactly as export_speedscope does.
is_json_path	Whether path names a JSON profile rather than an HDF5 one.
load_json	Parse a JSON profile into :class:ProfilingResults arguments.
read_json	Read a JSON profile back into :class:ProfilingResults.
write_json	Write one run to filepath as JSON, and return the path written.
write_json_file	Write document to filepath, gzip-compressed for a .gz name.

FORMAT_NAMEattributemodule attribute#

View source

FORMAT_NAME = 'scope-profiler-profile'

FORMAT_VERSIONattributemodule attribute#

View source

FORMAT_VERSION = 1

JSON_SUFFIXESattributemodule attribute#

View source

JSON_SUFFIXES = ('.json', '.json.gz')

JSONProfileErrorclass#

View source

class JSONProfileError(ValueError)

Bases: ValueError

Raised when a file is not a scope-profiler JSON profile.

build_json_documentfunction#

View source

def build_json_document(results: ProfilingResults, include=None, exclude=None, ranks: list[int] | int | None = None) -> dict

Build the JSON document describing one run.

Parameters

results : ProfilingResults The run to serialize, from a file or straight out of ProfileManager.finalize(return_results=True). include, exclude : list[str] | str, optional Region name filters, as for the plotting functions. ranks : list[int] | int, optional Ranks to keep (default: every rank the run recorded).

Returns

dict A JSON-serializable document; see :func:write_json.

export_jsonfunction#

View source

def export_json(profiling_data: ProfilingResults | Sequence[ProfilingResults], filepath: str | Path, ranks: list[int] | int | None = None, include: list[str] | str | None = None, exclude: list[str] | str | None = None, verbose: bool = True, indent: int | None = None) -> list[Path]

Write one JSON document per run, exactly as export_speedscope does.

Parameters

profiling_data : ProfilingResults | Sequence[ProfilingResults] The run(s) to export: file runs, in-memory results, or a mix. filepath : str | Path Base output path, e.g. figures/profile.json. Ending it in .gz compresses the output. The run’s label is appended to the stem when more than one run is exported. ranks : list[int] | int, optional Ranks to export (default: every rank). include, exclude : list[str] | str, optional Region name filters, as for the plotting functions. indent : int, optional Passed to json.dumps; the default writes the document on one line.

Returns

list[Path] The files written, in the order they were written.

is_json_pathfunction#

View source

def is_json_path(path) -> bool

Whether path names a JSON profile rather than an HDF5 one.

load_jsonfunction#

View source

def load_json(file_path: str | Path, verbose: bool = False) -> dict

Parse a JSON profile into :class:ProfilingResults arguments.

The JSON twin of :func:~scope_profiler.h5reader.load_h5, and the parsing half of :func:read_json.

read_jsonfunction#

View source

def read_json(file_path: str | Path, verbose: bool = False) -> ProfilingResults

Read a JSON profile back into :class:ProfilingResults.

The JSON twin of :func:~scope_profiler.h5reader.read_h5::

results = read_json("profiling_data.json")
results.print_summary()

write_jsonfunction#

View source

def write_json(results: ProfilingResults, filepath: str | Path, *, include=None, exclude=None, ranks: list[int] | int | None = None, indent: int | None = None) -> Path

Write one run to filepath as JSON, and return the path written.

write_json_filefunction#

View source

def write_json_file(filepath: str | Path, document: dict, indent=None) -> Path

Write document to filepath, gzip-compressed for a .gz name.