Diagnostics

Diagnostics are part of the Document result. They are machine-readable and designed for callers that need to surface recoverable parser warnings or errors.

from rtfstruct import parse_rtf

document = parse_rtf(r"{\rtf1\u999999?}")

for diagnostic in document.diagnostics:
    print(diagnostic.severity.value, diagnostic.code, diagnostic.message)

Diagnostics for parser, exporter, and writer recovery.

This module owns machine-readable diagnostic records and capped diagnostic collection. It does not decide parser recovery policy; parser and writer modules create diagnostics when they recover from malformed or unsupported input.

class rtfstruct.diagnostics.Diagnostic(code, message, severity, offset=None, control_word=None, destination=None)

Machine-readable parser, exporter, or writer diagnostic.

Parameters:

• code (str)

• message (str)

• severity (Severity)

• offset (int | None)

• control_word (str | None)

• destination (str | None)

code

Stable diagnostic code.

Type:

str

message

Human-readable explanation.

Type:

str

severity

Severity of the condition.

Type:

rtfstruct.diagnostics.Severity

offset

Optional byte or character offset where the condition occurred.

Type:

int | None

control_word

Optional RTF control word associated with the diagnostic.

Type:

str | None

destination

Optional RTF destination associated with the diagnostic.

Type:

str | None

class rtfstruct.diagnostics.Diagnostics(max_diagnostics=10000, per_code_limit=20)

Capped and deduplicated diagnostic collector.

The collector records the first few diagnostics for each code and suppresses repeated duplicates. Suppression summaries can be emitted at the end of a parse so repeated defects do not overwhelm downstream tooling.

Parameters:

• max_diagnostics (int)

• per_code_limit (int)

add(code, message, severity=Severity.WARNING, *, offset=None, control_word=None, destination=None)

Add a diagnostic if collection limits allow it.

Parameters:

• code (str) – Stable diagnostic code.

• message (str) – Human-readable diagnostic text.

• severity (Severity) – Severity level.

• offset (int | None) – Optional source offset.

• control_word (str | None) – Optional related control word.

• destination (str | None) – Optional active destination.

Return type:

None

finalize()

Append suppression summaries and return retained diagnostics.

Return type:

list[Diagnostic]

property items: list[Diagnostic]

Return retained diagnostics in insertion order.

class rtfstruct.diagnostics.Severity(value)

Diagnostic severity levels.