diag_tree

Utility functions for diagnostic trees.

Functions:

• aggregate –

  Aggregate a diagnostic tree into a single status, keeping the highest severity status.

• flatten –

  Flatten a diagnostic tree into a dictionary of path -> status.

• precedence –

  Return the precedence (= severity) of a diagnostic status.

• prettify –

  Stringify a diagnostic tree in a human-readable format.

• to_diag_tree –

  Convert a diagnostic status, list or dictionary to a diagnostic tree.

aggregate

aggregate(
    diag_tree: DiagTree, default: DiagStatus | None = None
) -> DiagStatus

Aggregate a diagnostic tree into a single status, keeping the highest severity status.

The final diagnostic message is the one of the highest severity status. If there are multiple statuses with the same severity, the message of one of them is used.

Parameters:

• diag_tree (DiagTree) –

  The diagnostic tree to aggregate

• default (DiagStatus | None, default: None ) –

  The default status to return if the tree is empty, or if none of the statuses in the tree have a higher severity than the default.

Raises:

• ValueError –

  If the tree is invalid (e.g. uninitialized)

Returns:

• DiagStatus –

  The aggregated diagnostic status

flatten

flatten(diag_tree: DiagTree) -> dict[str, DiagStatus | str]

Flatten a diagnostic tree into a dictionary of path -> status.

The components of the path are separated by dots.

Examples:

• Ok() -> {"status": Ok()}

• [Ok(), Error(msg="my message")] ->

  {
      "0.status": Ok(),
      "1.status": Error(my message)
  }
  

Parameters:

• diag_tree (DiagTree) –

  The diagnostic tree to flatten

Returns:

• dict[str, DiagStatus | str] –

  The flattened diagnostic tree

precedence

precedence(status: DiagStatus) -> int

Return the precedence (= severity) of a diagnostic status.

Parameters:

• status (DiagStatus) –

  The diagnostic status to get the precedence of

Raises:

• ValueError –

  If the status is invalid (e.g. uninitialized)

Returns:

• int –

  0 for Ok, 1 for Unknown, 2 for Warning, 3 for Error

prettify

prettify(diag_tree: DiagTree, indent: int = 0) -> str

Stringify a diagnostic tree in a human-readable format.

Examples:

• Ok() -> Ok
• Error(msg="my message") -> Error(my message)
• [] -> []

• [Ok(), Error(msg="my message")] ->

  [
      Ok,
      Error(my message)
  ]
  

  * {"a": Ok(), "b": Error(msg="my message")} ->

  {
      a: Ok,
      b: Error(my message)
  }
  

Parameters:

• diag_tree (DiagTree) –

  The diagnostic tree to stringify

• indent (int, default: 0 ) –

  The number of spaces to indent per level. Defaults to 0.

Raises:

• ValueError –

  If the tree is invalid (e.g. uninitialized)

Returns:

• str –

  The stringified diagnostic tree

to_diag_tree

to_diag_tree(
    proto: (
        DiagTree
        | DiagStatus
        | Ok
        | Warning
        | Error
        | Unknown
        | list
        | dict
        | str
    ),
) -> DiagTree

Convert a diagnostic status, list or dictionary to a diagnostic tree.

If performed on a list or dictionary, the conversion is performed recursively and the items have to be convertible themselves.

Parameters:

• proto (DiagTree | DiagStatus | Ok | Warning | Error | Unknown | list | dict | str) –

  The diagnostic status, list or dictionary to convert

Raises:

• ValueError –

  If the input is not convertible

Returns:

• DiagTree –

  The converted diagnostic tree