Exceptions API¶

This section provides the complete API reference for QuantumEngine’s exception system.

Core Exceptions Module ¶

Exceptions for QuantumEngine.

This module contains custom exceptions used throughout the QuantumEngine package.

exception quantumengine.exceptions.QuantumEngineError[source]¶

Bases: Exception

Base exception class for QuantumEngine.

All other exceptions in the package inherit from this class.

exception quantumengine.exceptions.ConnectionError[source]¶

Bases: QuantumEngineError

Raised when a connection to the database cannot be established.

This exception is raised when there is an issue connecting to the SurrealDB server, such as network errors, authentication failures, or server unavailability.

exception quantumengine.exceptions.ValidationError(message, errors=None, field_name=None)[source]¶

Bases: QuantumEngineError

Raised when document validation fails.

This exception is raised when a document fails validation, such as when a required field is missing or a field value is of the wrong type.

errors¶: Dictionary of validation errors by field

field_name¶: Name of the field that failed validation, if applicable

__init__(message, errors=None, field_name=None)[source]¶

Initialize a ValidationError.

Parameters:

message (str) – The error message
errors (Dict[str, Any] | None) – Dictionary of validation errors by field
field_name (str | None) – Name of the field that failed validation, if applicable

exception quantumengine.exceptions.DoesNotExist[source]¶

Bases: QuantumEngineError

Raised when a document does not exist in the database.

This exception is raised when attempting to retrieve a document that does not exist in the database, such as when using the get() method with a query that matches no documents.

exception quantumengine.exceptions.MultipleObjectsReturned[source]¶

Bases: QuantumEngineError

Raised when multiple documents are returned when only one was expected.

This exception is raised when a query that is expected to return a single document returns multiple documents, such as when using the get() method with a query that matches multiple documents.

exception quantumengine.exceptions.OperationError[source]¶

Bases: QuantumEngineError

Raised when a database operation fails.

This exception is raised when a database operation fails, such as when attempting to create a document with an invalid schema or when a query fails due to a syntax error.

exception quantumengine.exceptions.InvalidQueryError[source]¶

Bases: QuantumEngineError

Raised when a query is invalid.

This exception is raised when a query is invalid, such as when using an unsupported operator or when a query is malformed.

Base Exception Classes ¶

QuantumEngineException ¶

Base exception class for all QuantumEngine exceptions.

Validation Exceptions ¶

ValidationError ¶

Base class for validation-related exceptions.

class quantumengine.exceptions.ValidationError(message, errors=None, field_name=None)[source]¶

Bases: QuantumEngineError

Raised when document validation fails.

This exception is raised when a document fails validation, such as when a required field is missing or a field value is of the wrong type.

errors¶: Dictionary of validation errors by field

field_name¶: Name of the field that failed validation, if applicable

__init__(message, errors=None, field_name=None)[source]¶

Initialize a ValidationError.

Parameters:

message (str) – The error message
errors (Dict[str, Any] | None) – Dictionary of validation errors by field
field_name (str | None) – Name of the field that failed validation, if applicable

FieldValidationError ¶

Raised when field validation fails.

DocumentValidationError ¶

Raised when document-level validation fails.

Database Exceptions ¶

DatabaseError ¶

Base class for database-related exceptions.

ConnectionError ¶

Raised when database connection fails.

class quantumengine.exceptions.ConnectionError[source]¶

Bases: QuantumEngineError

Raised when a connection to the database cannot be established.

This exception is raised when there is an issue connecting to the SurrealDB server, such as network errors, authentication failures, or server unavailability.

QueryError ¶

Raised when query execution fails.

TransactionError ¶

Raised when transaction operations fail.

Backend-Specific Exceptions ¶

BackendError ¶

Base class for backend-specific exceptions.

SurrealDBError ¶

SurrealDB-specific exception.

ClickHouseError ¶

ClickHouse-specific exception.

Document Exceptions ¶

DocumentError ¶

Base class for document-related exceptions.

DoesNotExist ¶

Raised when querying for a non-existent object.

class quantumengine.exceptions.DoesNotExist[source]¶

Bases: QuantumEngineError

Raised when a document does not exist in the database.

This exception is raised when attempting to retrieve a document that does not exist in the database, such as when using the get() method with a query that matches no documents.

MultipleObjectsReturned ¶

Raised when get() returns multiple objects.

class quantumengine.exceptions.MultipleObjectsReturned[source]¶

Bases: QuantumEngineError

Raised when multiple documents are returned when only one was expected.

This exception is raised when a query that is expected to return a single document returns multiple documents, such as when using the get() method with a query that matches multiple documents.