Errors

Crease's error model is pydantic-shaped: every problem the library surfaces — whether structural (template can't map the file) or cell-level (a value violated a constraint) — is represented as the same Error type, with the same five fields.

Error dataclass

Error(
    type: str,
    loc: tuple[str | int | None, ...],
    msg: str = "",
    input: Any = None,
    ctx: dict[str, Any] = dict(),
    severity: Severity = "cell",
)

A single problem surfaced by crease.

Fields mirror pydantic.ValidationError.errors() entries, with one crease addition: severity distinguishes structural errors (the template can't map the file at all) from cell-level errors (an individual value violated a constraint).

Attributes:

Name	Type	Description
type	str	Stable machine code for routing — e.g. "wrong_type", "missing_required", "pattern_mismatch". See the README for the full taxonomy.
loc	tuple[str | int | None, ...]	(entity, row, field) tuple identifying where the problem was found. Any element may be None for errors that don't apply to a specific row or field (e.g. missing_tab).
msg	str	Human-readable description.
input	Any	The offending value, if applicable. None for structural errors with no specific cell.
ctx	dict[str, Any]	Extra context — for example {"likely_cause": "excel_autoconvert"} when a string field received what looks like an Excel-autoconverted date.
severity	Severity	"cell" or "structural". Derived from type.

type instance-attribute

type: str

loc instance-attribute

loc: tuple[str | int | None, ...]

msg class-attribute instance-attribute

msg: str = ''

input class-attribute instance-attribute

input: Any = None

ctx class-attribute instance-attribute

ctx: dict[str, Any] = field(default_factory=dict)

severity class-attribute instance-attribute

severity: Severity = 'cell'

is_structural property

is_structural: bool

is_cell property

is_cell: bool

to_dict

to_dict() -> dict[str, Any]

Serialize to a plain dict suitable for JSON output.

ValidationError

ValidationError(
    errors: list[Error], message: str | None = None
)

Bases: Exception

Raised by halt-by-default projection methods when crease has errors to report.

The exception carries the full Error list — same shape as Report.errors() would have produced. Pattern after Pydantic's ValidationError:

try:
    orders = result.to_pydantic("order", model=Order)
except crease.ValidationError as e:
    for err in e.errors():
        print(err.type, err.loc, err.msg)

errors

errors() -> list[Error]

Return the full list of errors. Same shape as Report.errors().

error_count

error_count() -> int

Error type taxonomy

The error.type field is a stable machine code safe to route on. The full taxonomy is in the README's error table.

blocks: grammar (v2)

These extract-time codes fire when the blocks: grammar can't make sense of a file. All are severity: structural.

error.type	Fires when…
block_starts_not_found	A tab matches the block's tab_pattern but no cell matches starts_at anywhere in the configured column.
block_unterminated	ends_at is configured but no candidate row fires before the next starts_at match or EOF.
capture_no_match	A capture with required: true matches zero cells inside a block instance.
capture_multiple_matches	A capture with on_multiple: error matches more than one cell inside a block instance.
block_ref_not_found	An entity's block: field names a block that isn't declared in template.blocks. Surfaced at Template.model_validate time.

A capture whose value matches the regex but fails to coerce to the declared type (e.g. type: date with a value that doesn't fit any of date_formats) emits the existing wrong_type code, keyed to the capture field.