Errors⚓︎

errors ⚓︎

Structured table errors with source location details.

The package raises errors that are useful both to humans and to tools. Human messages explain what failed; stable codes and source coordinates let pytest, CLIs, and editor integrations render diagnostics without scraping strings.

Info

Row and column coordinates are one-based and refer to the original source table whenever a TableCell is available.

TableErrorCode ⚓︎

Bases: str, Enum

Stable machine-readable categories for table failures.

Human-readable messages may improve over time. Integrations should use these codes when grouping diagnostics or deciding how to present them.

Warning

Codes are part of the supported diagnostic contract. Prefer adding new codes over changing existing meanings.

TableError ⚓︎

TableError(
    message: str,
    *,
    schema: type | str | None = None,
    field: str | None = None,
    field_name: str | None = None,
    field_label: str | None = None,
    source_uri: str | None = None,
    row: int | None = None,
    column: int | None = None,
    item_id: Any = _UNSET,
    value: Any = _UNSET,
    source_value: Any = _UNSET,
    logical_value: Any = _UNSET,
    code: TableErrorCode | str = TABLE_ERROR,
    hint: str | None = None,
    severity: DiagnosticSeverity | str = ERROR,
    cause: BaseException | None = None,
)

Bases: ValueError

Represent one source-aware table diagnostic.

The structured attributes are intentionally public. Test runners and editor integrations can inspect them without parsing the human-readable error message.

Attributes:

message (str) –

Human-readable failure summary.
schema (str | None) –

Schema display name when known.
field (str | None) –

Legacy human-facing field label associated with the failure.
field_name (str | None) –

Python attribute name associated with the failure.
field_label (str | None) –

Authored field label associated with the failure.
source_uri (str | None) –

URI of the source document when known.
row (int | None) –

One-based source row.
column (int | None) –

One-based source column.
item_id (Any | None) –

Parsed item ID when the failing record has one.
value (Any | None) –

Legacy alias for the offending source value.
code (str) –

Stable machine-readable diagnostic code.
hint (str | None) –

Optional remediation text.

Info

TableError inherits ValueError so project validators can raise ordinary value errors while the schema lifecycle wraps them in a table-aware diagnostic.

Initialize one structured table diagnostic.

Parameters:

message (str) –

Human-readable failure summary.
schema (type | str | None, default: None ) –

Schema class or display name associated with the failure.
field (str | None, default: None ) –

Legacy human-facing field label.
field_name (str | None, default: None ) –

Python attribute name for the declared field.
field_label (str | None, default: None ) –

Authored canonical or alias label for the field.
source_uri (str | None, default: None ) –

URI of the source document when known.
row (int | None, default: None ) –

One-based source row.
column (int | None, default: None ) –

One-based source column.
item_id (Any, default: _UNSET ) –

Parsed item identifier when available.
value (Any, default: _UNSET ) –

Offending source value. Omit to represent "no value".
source_value (Any, default: _UNSET ) –

Original authored value, superseding value.
logical_value (Any, default: _UNSET ) –

Current value after table transformation.
code (TableErrorCode | str, default: TABLE_ERROR ) –

Stable diagnostic category.
hint (str | None, default: None ) –

Optional user-facing remediation.
severity (DiagnosticSeverity | str, default: ERROR ) –

Diagnostic severity.
cause (BaseException | None, default: None ) –

Original exception when this error wraps another failure.

Warning

Passing value=None means the offending value is explicitly None. Omit value entirely when no value should be reported.

message `property` ⚓︎

message: str

Return the human-readable failure message.

schema `property` ⚓︎

schema: str | None

Return the schema display name when known.

field `property` ⚓︎

field: str | None

Return the legacy human-facing field identifier.

field_name `property` ⚓︎

field_name: str | None

Return the declared Python field name when known.

field_label `property` ⚓︎

field_label: str | None

Return the authored field label when known.

source_uri `property` ⚓︎

source_uri: str | None

Return the source document URI when known.

row `property` ⚓︎

row: int | None

Return the one-based source row when known.

column `property` ⚓︎

column: int | None

Return the one-based source column when known.

item_id `property` ⚓︎

item_id: Any | None

Return the parsed item identifier when present.

has_item_id `property` ⚓︎

has_item_id: bool

Return whether an item identifier is present.

value `property` ⚓︎

value: Any | None

Return the legacy alias for the original source value.

source_value `property` ⚓︎

source_value: Any | None

Return the original authored value when present.

logical_value `property` ⚓︎

logical_value: Any | None

Return the current transformed value when present.

code `property` ⚓︎

code: str

Return the stable machine-readable diagnostic code.

hint `property` ⚓︎

hint: str | None

Return optional remediation text.

severity `property` ⚓︎

severity: DiagnosticSeverity

Return the diagnostic severity.

has_value `property` ⚓︎

has_value: bool

Return whether the diagnostic contains an offending value.

Returns:

bool –

True when value was supplied to the error constructor.

Info

This distinguishes an omitted value from an explicit None.

from_diagnostic `classmethod` ⚓︎

from_diagnostic(diagnostic: Diagnostic) -> TableError

Create a compatibility exception around an existing diagnostic.

from_cell `classmethod` ⚓︎

from_cell(
    message: str,
    cell: TableCell,
    *,
    schema: type | str | None = None,
    field: str | None = None,
    field_name: str | None = None,
    field_label: str | None = None,
    source_uri: str | None = None,
    item_id: Any = _UNSET,
    code: TableErrorCode | str = TABLE_ERROR,
    hint: str | None = None,
    severity: DiagnosticSeverity | str = ERROR,
    cause: BaseException | None = None,
) -> TableError

Create an error located at a cell's original source.

This helper is useful inside custom table transformations. It reports the source syntax, not merely the current transformed value.

Parameters:

message (str) –

Human-readable failure summary.
cell (TableCell) –

Source-aware cell that caused the error.
schema (type | str | None, default: None ) –

Schema class or display name associated with the failure.
field (str | None, default: None ) –

Legacy human-facing field label.
field_name (str | None, default: None ) –

Python attribute name for the declared field.
field_label (str | None, default: None ) –

Authored canonical or alias label for the field.
source_uri (str | None, default: None ) –

Source document URI, overriding the cell URI.
item_id (Any, default: _UNSET ) –

Parsed item identifier when available.
code (TableErrorCode | str, default: TABLE_ERROR ) –

Stable diagnostic category.
hint (str | None, default: None ) –

Optional user-facing remediation.
severity (DiagnosticSeverity | str, default: ERROR ) –

Diagnostic severity.
cause (BaseException | None, default: None ) –

Original exception when this error wraps another failure.

Returns:

TableError –

A TableError populated from cell source coordinates.

Example

raise TableError.from_cell(
    "Invalid compact range",
    source_cell,
    schema=ContentTable,
)

str ⚓︎

__str__() -> str

Return a compact message with structured context appended.

Returns:

str –

The human-facing diagnostic text used by ValueError and CLI
str –

text output.

Info

The string is intentionally readable, but integrations should prefer attributes such as code, row, and field.

TableErrors ⚓︎

TableErrors(errors: list[TableError] | tuple[TableError, ...])

Bases: ValueError

Aggregate raised when collect mode finds several table failures.

The contained errors retain their normal structured attributes and source locations. The aggregate itself is intentionally small so test runners, editor extensions, and command-line tools can render diagnostics in the format most useful to their users.

Attributes:

errors –

Immutable tuple of collected TableError objects.

Info

Collection preserves discovery order so rendered diagnostics follow the table as closely as possible.

Initialize an aggregate of one or more diagnostics.

Parameters:

errors (list[TableError] | tuple[TableError, ...]) –

Non-empty sequence of structured table errors.

Raises:

ValueError –

If errors is empty.

Warning

Empty aggregates are rejected because their string representation would imply a failure without any actionable diagnostic.

diagnostics `property` ⚓︎

diagnostics: tuple[Diagnostic, ...]

Return underlying immutable diagnostics in discovery order.

iter ⚓︎

__iter__() -> Iterator[TableError]

Iterate over diagnostics in discovery order.

Returns:

Iterator[TableError] –

Iterator over contained TableError objects.

Info

This lets callers use list(exc) or simple loops without reaching into exc.errors directly.

len ⚓︎

__len__() -> int

Return the number of collected diagnostics.

Returns:

int –

Count of contained TableError objects.

Info

len(exc) mirrors the number reported in the aggregate message.

str ⚓︎

__str__() -> str

Return a numbered multi-line diagnostic summary.

Returns:

str –

Human-readable text containing every collected error.

Info

The aggregate string is convenient for test failures; structured renderers should iterate over errors instead.

SchemaDefinitionError ⚓︎

SchemaDefinitionError(message: str, *, schema: str | None = None)

Bases: ValueError

Report an invalid schema declaration before table input is parsed.

Attributes:

message –

Human-readable declaration problem.
schema –

Name of the schema being created when available.

Warning

These errors normally occur during class creation. Explicit variant families may be completed by decorators, so their family-wide checks run when the family is described or first finalized for parsing.

Initialize a schema-definition failure.

Parameters:

message (str) –

Human-readable declaration problem.
schema (str | None, default: None ) –

Optional schema name associated with the problem.

Info

The formatted exception includes the schema name because these failures often occur during import before any table is parsed.

Errors⚓︎

errors ⚓︎

TableErrorCode ⚓︎

TableError ⚓︎

message property ⚓︎

schema property ⚓︎

field property ⚓︎

field_name property ⚓︎

field_label property ⚓︎

source_uri property ⚓︎

row property ⚓︎

column property ⚓︎

item_id property ⚓︎

has_item_id property ⚓︎

value property ⚓︎

source_value property ⚓︎

logical_value property ⚓︎

code property ⚓︎

hint property ⚓︎

severity property ⚓︎

has_value property ⚓︎

from_diagnostic classmethod ⚓︎

from_cell classmethod ⚓︎

__str__ ⚓︎

TableErrors ⚓︎

diagnostics property ⚓︎

__iter__ ⚓︎

__len__ ⚓︎

__str__ ⚓︎

SchemaDefinitionError ⚓︎

message `property` ⚓︎

schema `property` ⚓︎

field `property` ⚓︎

field_name `property` ⚓︎

field_label `property` ⚓︎

source_uri `property` ⚓︎

row `property` ⚓︎

column `property` ⚓︎

item_id `property` ⚓︎

has_item_id `property` ⚓︎

value `property` ⚓︎

source_value `property` ⚓︎

logical_value `property` ⚓︎

code `property` ⚓︎

hint `property` ⚓︎

severity `property` ⚓︎

has_value `property` ⚓︎

from_diagnostic `classmethod` ⚓︎

from_cell `classmethod` ⚓︎

str ⚓︎

diagnostics `property` ⚓︎

iter ⚓︎

len ⚓︎

str ⚓︎