Skip to content

caxton.core.errors

Every library exception inherits from CaxtonError and carries a semantic path plus an immutable structured-context snapshot. CaxtonTypeError and CaxtonValueError also subclass the Python built-ins, so existing handlers keep working.

See Testing and diagnostics for help locating failures in the document pipeline.

Base

Classes:

CaxtonError dataclass 

CaxtonError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: Exception

Base class for every public caxton exception.

CaxtonTypeError dataclass 

CaxtonTypeError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: CaxtonError, TypeError

Raised when a public argument has an invalid runtime type.

CaxtonValueError dataclass 

CaxtonValueError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: CaxtonError, ValueError

Raised when a public argument value violates a local invariant.

InvalidOperationError dataclass 

InvalidOperationError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: CaxtonError

Raised when an operation is invalid for the current document state.

UnsupportedFeatureError dataclass 

UnsupportedFeatureError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: CaxtonError

Raised when the selected target cannot represent a requested feature.

Validation

Classes:

  • ValidationError –

    Raised for one or more errors in a semantic document model.

  • SchemaError –

    Raised when a document schema is invalid.

  • ShapeError –

    Raised when data dimensions do not match the document schema.

  • ColumnNotFoundError –

    Raised when a referenced column does not exist.

  • CyclicReferenceError –

    Raised when semantic references form a dependency cycle.

  • DuplicateColumnError –

    Raised when a schema contains the same column more than once.

  • Issue –

    One validation problem with machine-readable context.

  • Notification –

    Collect validation issues and raise them as one error.

ValidationError dataclass 

ValidationError(message: str = 'Document validation failed', *, path: str | None = None, context: Mapping[str, Any] = dict(), issues: tuple[Issue, ...] = tuple())

Bases: CaxtonError

Raised for one or more errors in a semantic document model.

SchemaError dataclass 

SchemaError(message: str = 'Document validation failed', *, path: str | None = None, context: Mapping[str, Any] = dict(), issues: tuple[Issue, ...] = tuple())

Bases: ValidationError

Raised when a document schema is invalid.

ShapeError dataclass 

ShapeError(message: str = 'Document validation failed', *, path: str | None = None, context: Mapping[str, Any] = dict(), issues: tuple[Issue, ...] = tuple())

Bases: ValidationError

Raised when data dimensions do not match the document schema.

ColumnNotFoundError dataclass 

ColumnNotFoundError(message: str = 'Document validation failed', *, path: str | None = None, context: Mapping[str, Any] = dict(), issues: tuple[Issue, ...] = tuple(), column: str)

Bases: SchemaError

Raised when a referenced column does not exist.

CyclicReferenceError dataclass 

CyclicReferenceError(message: str = 'Document validation failed', *, path: str | None = None, context: Mapping[str, Any] = dict(), issues: tuple[Issue, ...] = tuple(), column: str, cycle: tuple[str, ...])

Bases: SchemaError

Raised when semantic references form a dependency cycle.

DuplicateColumnError dataclass 

DuplicateColumnError(message: str = 'Document validation failed', *, path: str | None = None, context: Mapping[str, Any] = dict(), issues: tuple[Issue, ...] = tuple(), column: str)

Bases: SchemaError

Raised when a schema contains the same column more than once.

Issue dataclass 

Issue(message: str, path: str | None = None, code: str | None = None, context: Mapping[str, Any] = dict())

One validation problem with machine-readable context.

Methods:

  • from_error –

    Create an issue while preserving a validation error's context.

from_error classmethod 

from_error(error: ValidationError) -> Self

Create an issue while preserving a validation error's context.

Returns:

  • Self –

    An issue containing the error message, path, and context.

Notification dataclass 

Notification()

Collect validation issues and raise them as one error.

Methods:

  • add –

    Add an issue, validation error, or plain validation message.

  • extend –

    Add several issues while preserving their order.

  • raise_if_errors –

    Raise the configured aggregate error if validation found issues.

Attributes:

issues property 

issues: tuple[Issue, ...]

Collected issues as an immutable snapshot.

has_errors property 

has_errors: bool

Whether at least one issue has been collected.

add 

add(issue: Issue | ValidationError | str, *, path: str | None = None, code: str | None = None, context: Mapping[str, Any] | None = None) -> Issue

Add an issue, validation error, or plain validation message.

Returns:

  • Issue –

    The normalized issue added to this notification.

extend 

extend(issues: Iterable[Issue | ValidationError]) -> None

Add several issues while preserving their order.

raise_if_errors 

raise_if_errors(message: str = 'Document validation failed', *, error_class: type[ValidationError] = ValidationError) -> None

Raise the configured aggregate error if validation found issues.

error_class selects the raised validation error, so a caller that collects schema or shape problems reports them under their own type.

Raises:

Data

Classes:

DataSourceError dataclass 

DataSourceError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: CaxtonError

Base class for data ingestion and row evaluation failures.

UnsupportedDataSourceError dataclass 

UnsupportedDataSourceError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: DataSourceError

Raised when an input cannot be interpreted as row-oriented data.

DataSourceConsumedError dataclass 

DataSourceConsumedError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: DataSourceError

Raised when a one-shot source is iterated more than once.

DataSourceIterationError dataclass 

DataSourceIterationError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict(), source_type: str, row_index: int)

Bases: DataSourceError

Raised when obtaining the next row from a data source fails.

DataEvaluationError dataclass 

DataEvaluationError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: DataSourceError

Base class for failures while evaluating row data.

FieldAccessError dataclass 

FieldAccessError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict(), field: str, row_type: str, row_index: int | None = None)

Bases: DataEvaluationError

Raised when an existing attribute fails while being read.

MissingFieldError dataclass 

MissingFieldError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict(), field: str, row_type: str, row_index: int | None = None)

Bases: DataSourceError

Raised when a row has no requested field.

SourceEvaluationError dataclass 

SourceEvaluationError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict(), column: str, row_type: str, row_index: int)

Bases: DataEvaluationError

Raised when a callable or expression source cannot be evaluated.

AggregateEvaluationError dataclass 

AggregateEvaluationError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: DataEvaluationError

Raised when an aggregation callable or its result is invalid.

CyclicColumnError dataclass 

CyclicColumnError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict(), column: str, row_index: int | None = None)

Bases: DataEvaluationError

Raised when semantic columns reference each other in a cycle.

GroupingError dataclass 

GroupingError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: DataEvaluationError

Raised when declared group values cannot be ordered.

MatrixConflictError dataclass 

MatrixConflictError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: DataEvaluationError

Raised when an unaggregated matrix cell receives multiple values.

Rendering and templates

Classes:

RenderError dataclass 

RenderError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: CaxtonError

Raised when a document cannot be rendered.

OutputError dataclass 

OutputError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: RenderError

Raised when artifact output cannot be delivered to its target.

BackendError dataclass 

BackendError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict(), backend: str | None = None)

Bases: RenderError

Wrap an implementation-specific renderer failure.

TemplateError dataclass 

TemplateError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: RenderError

Base error for template inspection, resolution, and rendering.

TemplateFormatError dataclass 

TemplateFormatError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: TemplateError

Raised when a template format cannot be selected safely.

TemplateRefError dataclass 

TemplateRefError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: TemplateError

Base error for invalid logical template targets.

MissingTemplateRefError dataclass 

MissingTemplateRefError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: TemplateRefError

Raised when a logical reference does not exist in the template.

AmbiguousTemplateRefError dataclass 

AmbiguousTemplateRefError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: TemplateRefError

Raised when a logical reference has more than one applicable target.

IncompatibleTemplateRefError dataclass 

IncompatibleTemplateRefError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: TemplateRefError

Raised when a target cannot accept the declared semantic content.

InvalidTemplateRefError dataclass 

InvalidTemplateRefError(message: str, *, path: str | None = None, context: Mapping[str, Any] = dict())

Bases: TemplateRefError

Raised when a template target is malformed or cannot be located.

Warnings

Classes:

CaxtonWarning

Bases: Warning

Base class for every warning emitted by caxton.

DocumentWarning

Bases: CaxtonWarning

Base category retained for document-generation warnings.

PerformanceWarning

Bases: DocumentWarning

Warn about an operation with a potentially surprising runtime cost.

ExperimentalFeatureWarning

Bases: DocumentWarning

Warn that an API or capability is experimental.