plesty.sdk.report

The report artifacts a module publishes about its own quality.

A module publishes two kinds of document under reports/, sharing one envelope so a consumer reads either the same way:

reports/
  check.json                    plesty check            committed
  <instrument>/
    field-test.json             field test              committed
  *.md                          every report            git-ignored
  *.jsonl                       raw per-run records     git-ignored

check.json sits at the top because the standard gates are a property of the module and have no instrument. field-test.json is written by plesty.lib.test.field_test after a run against real hardware, and belongs to a module and the hardware it ran against — hence the directory.

This module owns the check half and reads the field-test half. The two are written by different tools at different times, which is the reason they are two files: a merged one would be a write race between plesty check and a hardware run.

Only the markdown and JSONL forms carry the host, the address and the driver’s own error messages, and the scaffold git-ignores them. Everything here is either derived from the module’s own source — already public — or is a gate result.

Attributes

`SCHEMA_VERSION`
`_TOOLING_PACKAGES`
`REPORTS_DIRNAME`
`GATE_CATALOG`

Exceptions

ReportError

A published report is missing, malformed, or from a contract we cannot read.

Classes

`GateRecord`	One gate's outcome, as a published page shows it.
`CheckReport`	The standard gates, as `check.json`.

Functions

`tooling_info`(→ dict[str, str])	Return the versions of the packages that decide what a run checked.
`module_info`(→ dict[str, Any])	Build the shared `module` block of a report envelope.
`read_field_test_reports`(→ list[tuple[pathlib.Path, ...)	Read every published `field-test.json` under the module's `reports/`.
`field_latencies`(→ dict[str, float])	Return the measured call time of everything a field test reached.
`_keep_slowest`(→ None)	Record calls' median against name, keeping the slowest seen.
`error_findings`(→ list[dict[str, Any]])	Return the `error` findings of a field test document.
`_require_known_version`(→ None)	Refuse a document whose major version this SDK cannot render.
`_module_version`(→ str)	Resolve the module's version from its metadata or its git history.
`_repository_path`(→ str \| None)	Return the origin remote's path without its host, or `None`.
`_git`(→ str)	Run a read-only git command in project_dir, returning its output or `""`.
`_utc_now`(→ str)	Return the current UTC time as an ISO-8601 string with second precision.

Module Contents

plesty.sdk.report.SCHEMA_VERSION = '1.1'

plesty.sdk.report._TOOLING_PACKAGES = ('plesty-sdk', 'plesty-lib')

plesty.sdk.report.REPORTS_DIRNAME = 'reports'

plesty.sdk.report.GATE_CATALOG: dict[str, tuple[str, str, str]]

exception plesty.sdk.report.ReportError

Bases: RuntimeError

A published report is missing, malformed, or from a contract we cannot read.

Initialize self. See help(type(self)) for accurate signature.

class plesty.sdk.report.GateRecord

One gate’s outcome, as a published page shows it.

Variables:

key – Gate key used by plesty check.
number – Gate number or letter code, e.g. "7" or "d1".
name – Human-readable gate title.
tier – Which family the gate belongs to — sdk or a module type.
status – One of PASS, FAIL, SKIP.
reason – Why it skipped or failed. None when it passed.

key: str

number: str

name: str

tier: str

status: str

reason: str | None = None

to_dict() → dict[str, Any]

Return a JSON-serialisable mapping of the gate record.

Return type:: dict[str, Any]

class plesty.sdk.report.CheckReport

The standard gates, as check.json.

Every module has one: the standard gates run without an instrument. That is the difference from a field test report, whose absence is meaningful and is rendered as absence rather than as an empty section.

Variables:

module – Module identification — name, version, type, standard, repository.
standard – The compliance standard the run enforced.
gates – Gate outcomes in execution order.
coverage_percent – Measured test coverage, when gate 7 ran.
coverage_required – The threshold gate 7 enforces.

module: dict[str, Any]

standard: str

gates: list[GateRecord] = []

coverage_percent: float | None = None

coverage_required: float | None = None

record(key: str, status: str, reason: str | None = None) → None

Append one gate outcome.

Parameters:

key (str) – Gate key; unknown keys are recorded under their own name rather than dropped, so a gate added without a catalog entry is visible instead of silently missing.
status (str) – One of PASS, FAIL, SKIP.
reason (str | None) – Why it skipped or failed.

Return type:

None

record_missing_as_skipped(keys: tuple[str, Ellipsis], reason: str) → None

Record every gate in keys that has no outcome yet.

A run that stopped at the first failure must not read as a clean sweep of a shorter sequence — the gates that never ran say so, with why.

Parameters:

keys (tuple[str, Ellipsis]) – The full gate sequence for this standard.
reason (str) – Why the remaining gates did not run.

Return type:

None

property counts: dict[str, int]

Number of gates per status.

Return type:: dict[str, int]

property ok: bool

True when no gate failed. A skipped gate does not fail a run.

Return type:: bool

to_dict() → dict[str, Any]

Return the document, sharing its envelope with field-test.json.

Return type:: dict[str, Any]

write(project_dir: pathlib.Path) → pathlib.Path

Write <project_dir>/reports/check.json.

Parameters:: project_dir (pathlib.Path) – Root directory of the module.
Returns:: The path written.
Return type:: pathlib.Path

plesty.sdk.report.tooling_info() → dict[str, str]

Return the versions of the packages that decide what a run checked.

A green check.json says which gates passed but not what they were — the gate set, and what each gate does, is a property of the SDK and of plesty-lib, and both change. Two reports claiming “Device API Pipeline” can mean two different contracts (v0.4.0 dropped the two hardware gates, made the parameter and operation gates able to fail at all, and moved the schema gate onto doc_model()). Without this a reader cannot tell which of those a report is asserting.

Returns:: Package name to installed version, for each package that is installed. An absent package is left out rather than recorded as unknown.
Return type:: dict[str, str]

plesty.sdk.report.module_info(project_dir: pathlib.Path, pyproject_toml: dict[str, Any], standard: str) → dict[str, Any]

Build the shared module block of a report envelope.

Parameters:

project_dir (pathlib.Path) – Root directory of the module.
pyproject_toml (dict[str, Any]) – Parsed pyproject.toml content.
standard (str) – The compliance standard resolved for this run.

Returns:

Name, version, module type, standard and repository path.

Return type:

dict[str, Any]

plesty.sdk.report.read_field_test_reports(project_dir: pathlib.Path) → list[tuple[pathlib.Path, dict[str, Any]]]

Read every published field-test.json under the module’s reports/.

A module that has never been field-tested publishes none, and that is the honest rendering: “never run” and “ran and found nothing” are different facts, and a placeholder invites a reader to treat them as the same.

Parameters:: project_dir (pathlib.Path) – Root directory of the module.
Returns:: (path, document) pairs, sorted by path.
Raises:: ReportError – If a document is unreadable, is not an object, or declares a schema version this SDK does not know.
Return type:: list[tuple[pathlib.Path, dict[str, Any]]]

plesty.sdk.report.field_latencies(project_dir: pathlib.Path) → dict[str, float]

Return the measured call time of everything a field test reached.

Keyed by parameter key and operation name, in milliseconds, so the device documentation can label what was exercised on hardware with what it cost. A parameter’s figure is its query; an operation’s is the call.

Untested entries are absent rather than zero. A label on every entry is a label nobody reads, and one that appears is then a thing that happened rather than one that changed colour.

Where several instruments reached the same entry the slowest is kept. Two reports are two rigs, and documentation that promised the faster one would be read as a guarantee by whoever has the other.

Parameters:: project_dir (pathlib.Path) – Root directory of the module.
Returns:: Name → median milliseconds. Empty when nothing was ever field-tested.
Return type:: dict[str, float]

plesty.sdk.report._keep_slowest(latencies: dict[str, float], name: Any, calls: Any) → None

Record calls’ median against name, keeping the slowest seen.

Parameters:

latencies (dict[str, float]) – The mapping being built, updated in place.
name (Any) – Parameter key or operation name.
calls (Any) – The call record, or None when the entry was never reached.

Return type:

None

plesty.sdk.report.error_findings(document: dict[str, Any]) → list[dict[str, Any]]

Return the error findings of a field test document.

An error finding means the module declares an API the instrument does not have — it is telling the rig, a remote client and the manager’s API summary that something exists which does not. That is worth failing a publish over, which is what gate f1 does with this list.

Parameters:: document (dict[str, Any]) – A parsed field-test.json.
Return type:: list[dict[str, Any]]

plesty.sdk.report._require_known_version(path: pathlib.Path, document: dict[str, Any]) → None

Refuse a document whose major version this SDK cannot render.

Parameters:

path (pathlib.Path) – Where the document came from, for the error message.
document (dict[str, Any]) – The parsed document.

Raises:

ReportError – If the version is absent or of an unknown major.

Return type:

None

plesty.sdk.report._module_version(name: str, project: dict[str, Any], project_dir: pathlib.Path) → str

Resolve the module’s version from its metadata or its git history.

Parameters:

name (str) – Distribution name.
project (dict[str, Any]) – The [project] table.
project_dir (pathlib.Path) – Root directory of the module, for the git fallback.

Return type:

str

plesty.sdk.report._repository_path(project_dir: pathlib.Path) → str | None

Return the origin remote’s path without its host, or None.

The path is what every PLESTY surface links to and is public by construction; the host is dropped because it identifies an instance, not a module.

Parameters:: project_dir (pathlib.Path) – Root directory of the module.
Return type:: str | None

plesty.sdk.report._git(project_dir: pathlib.Path, *args: str) → str

Run a read-only git command in project_dir, returning its output or "".

Parameters:

project_dir (pathlib.Path)
args (str)

Return type:

str

plesty.sdk.report._utc_now() → str

Return the current UTC time as an ISO-8601 string with second precision.

Return type:: str