diagnostic

class diagnostic.DiagnosticStyle

Data about how to present a Diagnostic object.

This is a frozen dataclass, so you can’t change the values after creating the object and can use it as a key in a dictionary.

__init__(*, name, color, ascii_symbol, unicode_symbol)

Parameters:

• name (str) – The name of this style. This is used before the code.

• color (str) – The Rich markup “style” to use.

• ascii_symbol (str) – The symbol to use in an ASCII-only environment.

• unicode_symbol (str) – The symbol to use in a Unicode-capable environment.

Return type:

None

name: str

The name of this style. This is used before the code.

color: str

The Rich markup “style” to use.

ascii_symbol: str

The symbol to use in an ASCII-only environment.

unicode_symbol: str

The symbol to use in a Unicode-capable environment.

class diagnostic.Diagnostic

An object that holds diagnostic information to present to a reader.

style: ClassVar[DiagnosticStyle]

Data about how this diagnostic should be presented

docs_index: ClassVar[str | None] = None

URL to the documentation index page(s). Must contain a “{code}” placeholder, which will be replaced with the code of this instance.

__init__(*, code=None, message, causes, hint_stmt, note_stmt=None)

Parameters:

• code (str | None) – Maps to code.

• message (str | Text) – Maps to message.

• causes (list[str] | list[Text] | list[str | Text]) – Maps to causes.

• hint_stmt (str | Text | None) – Maps to hint_stmt.

• note_stmt (str | Text | None) – Maps to note_stmt.

Return type:

None

code: str | None = None

A unique code to help readers identify this in output, documentation, etc.

This should be a string of the form “name[-name-or-number]*”, where “name” is a string of letters and numbers, and “name-or-number” is a string of letters, numbers, and dashes.

message: str | rich.text.Text

A short description.

causes: Sequence[str | rich.text.Text]

A list of strings describing the causes.

note_stmt: str | rich.text.Text | None

A note with additional information, that’s not part of the “causes” but could be useful to know for the reader.

hint_stmt: str | rich.text.Text | None

A hint for what the reader might want to do next.

details_link: str | None

A link to more details about the problem.

This is determined automatically if code is set, and docs_index is set.

class diagnostic.DiagnosticError

Bases: Diagnostic, Exception

An exception that requires additional diagnostic information to be provided.

This is a subclass of Exception and can be used as a normal exception, with the typical exception handling mechanisms. It can also be printed using rich to get a pretty presentation of the error.

style: ClassVar[DiagnosticStyle] = DiagnosticStyle(name='error', color='red', ascii_symbol='x', unicode_symbol='×')

Data about how this diagnostic should be presented

class diagnostic.DiagnosticWarning

Bases: Diagnostic, Warning

A warning that requires additional diagnostic information to be provided.

This is a subclass of Warning and can be used as a normal warning, with the typical

style: ClassVar[DiagnosticStyle] = DiagnosticStyle(name='warning', color='yellow', ascii_symbol='!', unicode_symbol='!')

Data about how this diagnostic should be presented