ErrorRecord#

class scikitplot.corpus.ErrorRecord(code, category, message, stage=None, source_id=None, exception_type=None, traceback_text=None, details=<factory>)[source]#

One structured, serialisable diagnostic.

Parameters:

codestr: Stable machine-readable identifier, e.g. "ARCHIVE_MEMBER_REFUSED". Stable across releases so callers may branch on it.
categoryErrorCategory: Coarse classification, for counting and filtering.
messagestr: Human-readable description. Should name the specific subject.
stagestr or None, optional: Pipeline stage that produced the record, e.g. "read", "embed".
source_idstr or None, optional: Identifier of the affected input: a doc_id, path, URL or member name.
exception_typestr or None, optional: Class name of the originating exception, as a string. The exception object itself is deliberately not retained – see the module notes.
traceback_textstr or None, optional: Formatted traceback, attached only when a caller explicitly opts in via include_traceback=True.
detailsdict, optional: Additional JSON-compatible context.

Parameters:

code (str)
category (ErrorCategory)
message (str)
stage (str | None)
source_id (str | None)
exception_type (str | None)
traceback_text (str | None)
details (dict[str, Any])

Notes

Developer. frozen=True because a diagnostic describes something that already happened; mutating it after the fact would make a build manifest disagree with the run it describes.

Examples

>>> rec = ErrorRecord(
...     code="PARSE_FAILED",
...     category=ErrorCategory.PARSE,
...     message="malformed XML",
...     source_id="doc-1",
... )
>>> rec.code
'PARSE_FAILED'
>>> sorted(rec.to_dict())[:3]
['category', 'code', 'details']

A record built from an exception keeps the type name, not the object:

>>> try:
...     raise ValueError("boom")
... except ValueError as exc:
...     rec = ErrorRecord.from_exception(
...         exc, code="X", category=ErrorCategory.INTERNAL
...     )
>>> rec.exception_type
'ValueError'
>>> rec.traceback_text is None
True

category: ErrorCategory[source]#

code: str[source]#

details: dict[str, Any][source]#

exception_type: str | None = None#

classmethod from_dict(data)[source]#

Rebuild a record from to_dict output.

Parameters:

datadict: Mapping produced by to_dict.

Returns:

ErrorRecord

Parameters:

data (dict[str, Any])

Return type:

ErrorRecord

classmethod from_exception(exc, *, code, category, stage=None, source_id=None, include_traceback=False, details=None)[source]#

Build a record from exc without retaining the exception.

Parameters:

excBaseException: The originating exception. Only its type name and str() are kept.
codestr: Stable machine-readable identifier.
categoryErrorCategory or str: Coarse classification.
stagestr or None, optional: Pipeline stage.
source_idstr or None, optional: Identifier of the affected input.
include_tracebackbool, optional: When True, format and attach the traceback as text. Default False: a formatted traceback is a string and therefore safe to retain, but it is verbose, so it is opt-in.
detailsdict or None, optional: Additional JSON-compatible context.

Returns:

ErrorRecord: A record holding no reference to exc or its frames.

Parameters:

exc (BaseException)
code (str)
category (ErrorCategory | str)
stage (str | None)
source_id (str | None)
include_traceback (bool)
details (dict[str, Any] | None)

Return type:

ErrorRecord

Notes

Developer. This method is the reason the 139x retention measured in F-R11-02 does not recur: the exception is read and dropped inside this call, so no frame locals survive it.

message: str[source]#

source_id: str | None = None#

stage: str | None = None#

to_dict()[source]#

Return a JSON-compatible mapping.

Returns:

dict: All fields, with category rendered as its string value.

Return type:

dict[str, Any]

Examples

>>> import json
>>> rec = ErrorRecord(code="C", category=ErrorCategory.SOURCE, message="m")
>>> _ = json.dumps(rec.to_dict())

traceback_text: str | None = None#