error-handling

Overview

pydita uses a shared mutable dict as its error accumulator, passed by reference through every API call. Errors are never raised and swallowed silently — they are recorded as ErrorRecord objects keyed by a string identifier (usually an absolute file path or a key name).

All error utilities live in pydita.loggingutils.

Core types

SEVERITY enum

Ordered severity levels (ascending):

from pydita.loggingutils import SEVERITY

SEVERITY.OTHER   # 0 — unclassified
SEVERITY.DEBUG   # 1 — debug trace
SEVERITY.INFO    # 2 — informational
SEVERITY.ERROR   # 3 — recoverable error
SEVERITY.WARN    # 4 — warning (higher than ERROR in pydita's ordering)
SEVERITY.FATAL   # 5 — unrecoverable

Note: In pydita's OrderedEnum, WARN (4) is higher than ERROR (3). This is intentional — WARNings are considered more severe than recoverable ERRORs.

ErrorRecord

from pydita.loggingutils import ErrorRecord, SEVERITY

rec = ErrorRecord(
    err=exception,          # Exception — required
    operation="myFunc()",   # str — which function caught it
    severity=SEVERITY.ERROR,
    key="file://abs/path",  # str — the dict key this belongs to
    traceBack="...",        # str — traceback.format_exc() output
)

str(rec)  # '[ERROR] "file://path" myFunc(): <exception message>'

Recording errors

Direct function call

from pydita import loggingutils
import traceback

errors = {}

try:
    do_something()
except Exception as e:
    loggingutils.recordError(
        errors,
        key="my-operation",
        err=e,
        operation="do_something()",
        severity=loggingutils.SEVERITY.ERROR,
        traceBack=traceback.format_exc(),
    )

Via DitaContext

ctx.recordError(
    key="some-key",
    error=exception,
    operation="myProcessor()",
    severity=SEVERITY.WARN,
)
# Delegates to loggingutils.recordError(ctx.getErrors(), ...)

Errors dict structure

errors = {
    "/abs/path/to/file.ditamap": [ErrorRecord, ErrorRecord, ...],
    "key-name":                  [ErrorRecord],
}

• One key can have multiple ErrorRecord objects (e.g., multiple parse errors in the same file).
• The key is any string — typically a file URI, file path, or DITA key name.

Reporting errors

Full report string

from pydita import loggingutils

report = loggingutils.reportErrors(errors, showTraceBack=False)
print(report)
# Have 3 total errors:
# [ERROR] "path/to/sub.ditamap" resolveSubmap(): ...
# [WARN]  "key-name" constructKeySpace(): ...

Filter by severity

from pydita.loggingutils import SEVERITY

fatal_errors = {
    k: [r for r in recs if r.getSeverity() >= SEVERITY.FATAL]
    for k, recs in errors.items()
    if any(r.getSeverity() >= SEVERITY.FATAL for r in recs)
}

Check for any errors above a threshold

def has_errors(errors: dict, min_severity=SEVERITY.ERROR) -> bool:
    return any(
        r.getSeverity() >= min_severity
        for recs in errors.values()
        for r in recs
    )

Logging helpers

pydita provides Logger (abstract) and ConsoleLogger (concrete) for structured log output:

from pydita.loggingutils import ConsoleLogger, SEVERITY

log = ConsoleLogger(logging_level=SEVERITY.WARN)
log.debug("ignored — below WARN threshold")
log.warn("printed: [WARN] printed: ...")
log.error("printed: [ERROR] ...")
log.fatal("printed: [FATAL] ...")

# Print raw message without severity prefix
log.print("Raw message output")

Implement a custom logger by subclassing Logger and overriding _log_message():

from pydita.loggingutils import Logger, SEVERITY

class FileLogger(Logger):
    def __init__(self, path: str):
        super().__init__(logging_level=SEVERITY.INFO)
        self._file = open(path, "w")

    def _log_message(self, message, severity: SEVERITY):
        if severity >= self.get_logging_level():
            self._file.write(f"[{severity.name}] {message}\n")

Best practices

See also

• context-setup — how errors is shared across the full pipeline
• map-resolve — error patterns during map resolution