Skip to content

Errors and warnings

Every exception pefftacular raises derives from PeffError, and every non-fatal spec violation is reported as a PeffWarning. See Errors and warnings for usage.

pefftacular.PeffError

Bases: ValueError

Base class for all pefftacular errors.

Subclasses :class:ValueError for backwards compatibility with callers that catch ValueError.

pefftacular.PeffParseError 

PeffParseError(
    message: str,
    *,
    line: int | None = None,
    context: str | None = None,
    hint: str | None = None,
)

Bases: PeffError

Raised when PEFF input cannot be parsed.

Attributes:

Name Type Description
line

1-based absolute line number the failure was detected on, if known.
context

The offending text (e.g. the raw item that failed to parse).
hint

A short, actionable suggestion for how to fix the input.
Source code in src/pefftacular/errors.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def __init__(
    self,
    message: str,
    *,
    line: int | None = None,
    context: str | None = None,
    hint: str | None = None,
) -> None:
    self.line = line
    self.context = context
    self.hint = hint
    super().__init__(message if line is None else f"Line {line}: {message}")
    # Notes surface in tracebacks (PEP 678) without changing ``str(err)``,
    # so agents reading a stack trace see the offending text and the fix.
    if context is not None:
        self.add_note(f"offending text: {context!r}")
    if hint is not None:
        self.add_note(f"hint: {hint}")

pefftacular.PeffWriteError 

PeffWriteError(
    message: str,
    *,
    index: int | None = None,
    hint: str | None = None,
)

Bases: PeffError

Raised when a model object cannot be serialized to PEFF.

Every entry is checked before anything is written, so on this error the destination is left untouched.

Attributes:

Name Type Description
index

0-based position of the offending entry in the input, if known; None for header problems. The message then starts with Entry N:.
hint

A short, actionable suggestion for how to fix the model.
Source code in src/pefftacular/errors.py 
72
73
74
75
76
77
def __init__(self, message: str, *, index: int | None = None, hint: str | None = None) -> None:
    self.index = index
    self.hint = hint
    super().__init__(message if index is None else f"Entry {index}: {message}")
    if hint is not None:
        self.add_note(f"hint: {hint}")

pefftacular.PeffWarning

Bases: UserWarning

Category for non-fatal PEFF spec violations detected while reading.

Parsing stays permissive: the data is always returned, but anything that violates a spec MUST rule (out-of-range positions, missing required fields, header/entry-count mismatches, un-coercible custom values, …) is reported through this category. Because it subclasses :class:UserWarning, existing UserWarning filters keep working; agents that want to treat PEFF problems as hard errors can warnings.simplefilter("error", PeffWarning).