k4bench.plugin.event_schema

k4bench.plugin.event_schema

Version contract of the event timing plugin's <label>_events.json.

A file without schema_version is the legacy unversioned event format and is read as before. Both the analysis loader and the runner validate through :func:validate_event_schema, so a new version is accepted or refused in one place.

validate_event_schema

validate_event_schema(raw: object, *, source: str | Path | None = None) -> None

Raise ValueError unless raw is an event file this k4bench can read.

raw is the parsed JSON document; a root that is not an object is refused.

An absent schema_version is accepted as the legacy unversioned format. A present one must be a plain int (bool and float are refused) between 1 and :data:EVENT_SCHEMA_VERSION; a newer version is refused rather than parsed as a format it may not be.

Source code in k4bench/plugin/event_schema.py

def validate_event_schema(raw: object, *, source: str | Path | None = None) -> None:
    """Raise ``ValueError`` unless *raw* is an event file this k4bench can read.

    *raw* is the parsed JSON document; a root that is not an object is refused.

    An absent ``schema_version`` is accepted as the legacy unversioned format.
    A present one must be a plain ``int`` (``bool`` and ``float`` are refused)
    between 1 and :data:`EVENT_SCHEMA_VERSION`; a newer version is refused
    rather than parsed as a format it may not be.
    """
    where = f"{source}: " if source is not None else ""
    if not isinstance(raw, Mapping):
        raise ValueError(f"{where}event JSON root must be an object")
    if "schema_version" not in raw:
        return
    version = raw["schema_version"]
    if type(version) is not int or version < 1:
        raise ValueError(f"{where}malformed schema_version {version!r}")
    if version > EVENT_SCHEMA_VERSION:
        raise ValueError(
            f"{where}unsupported future schema_version {version} "
            f"(this k4bench reads <= {EVENT_SCHEMA_VERSION})"
        )