Skip to content

pydantable.errors

User-facing exceptions for validation, ingest, and engine contracts.

pydantable.errors

User-facing errors for schema and ingest contracts.

Most exceptions subclass :exc:ValueError (or :exc:PydantableUserError, which is a :class:ValueError subclass) so broad handlers in application code keep working. Prefer catching specific types in new code and map them to HTTP status codes in APIs (e.g. :exc:ColumnLengthMismatchError → 400 with FastAPI helpers).

PydantableUserError

Bases: ValueError

Base class for predictable validation and contract failures.

Subclasses :exc:ValueError so except ValueError still matches; use this base or a concrete subclass when you need to distinguish pydantable errors from other :exc:ValueError sources.

Source code in python/pydantable/errors.py 
16
17
18
19
20
21
22
class PydantableUserError(ValueError):
    """Base class for predictable validation and contract failures.

    Subclasses :exc:`ValueError` so ``except ValueError`` still matches; use this
    base or a concrete subclass when you need to distinguish pydantable errors from
    other :exc:`ValueError` sources.
    """

ColumnLengthMismatchError

Bases: PydantableUserError

Raised when per-column list lengths disagree for a rectangular table mapping.

Typical cause: constructing a dict[str, list] or equivalent where one column has a different row count than the others.

Source code in python/pydantable/errors.py 
25
26
27
28
29
30
class ColumnLengthMismatchError(PydantableUserError):
    """Raised when per-column list lengths disagree for a rectangular table mapping.

    Typical cause: constructing a ``dict[str, list]`` or equivalent where one column
    has a different row count than the others.
    """

MissingOptionalDependency

Bases: PydantableUserError

Raised when an optional dependency is required for the requested API.

Install the matching extra (for example pip install 'pydantable[sql]').

Source code in python/pydantable/errors.py 
33
34
35
36
37
class MissingOptionalDependency(PydantableUserError):
    """Raised when an optional dependency is required for the requested API.

    Install the matching extra (for example ``pip install 'pydantable[sql]'``).
    """

UnsupportedEngineOperationError

Bases: PydantableUserError, UnsupportedEngineOperationError

Raised when the active execution engine cannot perform a requested operation.

Inherits from :class:pydantable_protocol.exceptions.UnsupportedEngineOperationError so isinstance(exc, pydantable_protocol.UnsupportedEngineOperationError) matches errors raised by pydantable and by third-party engines.

Source code in python/pydantable/errors.py 
40
41
42
43
44
45
46
47
48
49
class UnsupportedEngineOperationError(
    PydantableUserError, _UnsupportedEngineOperationProtocol
):
    """Raised when the active execution engine cannot perform a requested operation.

    Inherits from
    :class:`pydantable_protocol.exceptions.UnsupportedEngineOperationError` so
    ``isinstance(exc, pydantable_protocol.UnsupportedEngineOperationError)``
    matches errors raised by ``pydantable`` and by third-party engines.
    """

unsupported_engine_operation 

unsupported_engine_operation(*, backend=None, operation, required_capability=None, hint=None)

Build a consistent UnsupportedEngineOperationError message.

Use this when an operation is unsupported due to engine capabilities or missing optional runtime components.

Source code in python/pydantable/errors.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def unsupported_engine_operation(
    *,
    backend: str | None = None,
    operation: str,
    required_capability: str | None = None,
    hint: str | None = None,
) -> UnsupportedEngineOperationError:
    """Build a consistent UnsupportedEngineOperationError message.

    Use this when an operation is unsupported due to engine capabilities or
    missing optional runtime components.
    """

    parts: list[str] = []
    if backend is not None:
        parts.append(f"Backend {backend!r}:")
    parts.append(f"unsupported operation {operation!r}.")
    if required_capability is not None:
        parts.append(f"Requires capability {required_capability!r}.")
    if hint is not None:
        parts.append(hint)
    return UnsupportedEngineOperationError(" ".join(parts))