Exceptions

dorsal.common.exceptions

APIError

APIError(
    status_code,
    detail,
    request_url=None,
    response_text=None,
)

Bases: DorsalClientError

HTTP Error (4xx/5xx).

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    status_code: int,
    detail: str | dict,
    request_url: str | None = None,
    response_text: str | None = None,
):
    self.status_code = status_code
    self.detail = detail
    self.request_url = request_url
    self.response_text = response_text

    if isinstance(detail, dict) and "detail" in detail:
        error_summary = detail["detail"]
    elif isinstance(detail, str):
        error_summary = detail
    else:
        error_summary = "No detail provided."

    base_message = f"API Error {status_code}: {error_summary}"
    super().__init__(base_message)

AnnotationConfigurationError

AnnotationConfigurationError(
    message, request_url=None, original_exception=None
)

Bases: FileAnnotatorError

Raised when the configuration for an annotation task is invalid.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

AnnotationExecutionError

AnnotationExecutionError(
    message, request_url=None, original_exception=None
)

Bases: FileAnnotatorError

Raised when an annotation model fails during execution or its output is invalid.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

AnnotationImportError

AnnotationImportError(
    message, request_url=None, original_exception=None
)

Bases: FileAnnotatorError

Raised when an annotation model or its validator fails to import.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

AnnotationValidationError

AnnotationValidationError(
    message, validation_errors=None, original_exception=None
)

Bases: FileAnnotatorError

Raised when a manually provided annotation fails validation against a schema.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    validation_errors: list | dict | str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message, original_exception=original_exception)
    self.validation_errors = validation_errors

ApiDataValidationError

ApiDataValidationError(
    message,
    *,
    request_url=None,
    validation_errors=None,
    response_text_snippet=None,
    original_exception=None
)

Bases: DorsalClientError

API response parsing/validation error.

Parameters:

Name	Type	Description	Default
message	str	A concise description of the validation/decoding error.	required
request_url	str | None	The URL that was being accessed.	None
validation_errors	list | dict | str | None	Specific validation errors (e.g., from Pydantic).	None
response_text_snippet	str | None	A snippet of the problematic response text.	None
original_exception	Exception | None	The underlying exception (e.g., JSONDecodeError, pydantic.ValidationError).	None

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    *,
    request_url: str | None = None,
    validation_errors: list | dict | str | None = None,
    response_text_snippet: str | None = None,
    original_exception: Exception | None = None,
):
    """
    Args:
        message: A concise description of the validation/decoding error.
        request_url: The URL that was being accessed.
        validation_errors: Specific validation errors (e.g., from Pydantic).
        response_text_snippet: A snippet of the problematic response text.
        original_exception: The underlying exception (e.g., JSONDecodeError, pydantic.ValidationError).
    """
    super().__init__(message)
    self.request_url = request_url
    self.validation_errors = validation_errors
    self.response_text_snippet = response_text_snippet
    self.original_exception = original_exception

AttributeConflictError

AttributeConflictError(message)

Bases: DorsalError

Raised when an attribute or key cannot be set because it already exists and overwriting is not permitted by the operation.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str):
    super().__init__(message=message)

AuthError

AuthError(message)

Bases: DorsalClientError

Error for client-side authentication or API key configuration issues.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str):
    super().__init__(message)

BadRequestError

BadRequestError(message, request_url, response_text=None)

Bases: DorsalClientError

400 Bad Request error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, request_url: str, response_text: str | None = None):
    self.request_url = request_url
    self.response_text = response_text
    super().__init__(f"{message}")

BaseModelProcessingError

BaseModelProcessingError(message, original_exception=None)

Bases: ModelRunnerError

Critical error during the processing of the essential base file model.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, original_exception: Exception | None = None):
    super().__init__(message)
    self.original_exception = original_exception

BatchSizeError

BatchSizeError(
    message, request_url=None, original_exception=None
)

Bases: ValidationError

The size of the request is too large.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

ConflictError

ConflictError(
    message, request_url=None, response_text=None
)

Bases: DorsalClientError

409 Conflict error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    response_text: str | None = None,
):
    self.request_url = request_url
    self.response_text = response_text
    full_message = f"{message}" if request_url else message
    super().__init__(full_message)

DataQualityError

DataQualityError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Raised when a data quality rule triggers it.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

DatasetExistsError

DatasetExistsError(
    message, request_url=None, response_text=None
)

Bases: ConflictError

Dataset exists.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    response_text: str | None = None,
):
    self.request_url = request_url
    self.response_text = response_text
    full_message = f"{message}" if request_url else message
    super().__init__(full_message)

DatasetTypeError

DatasetTypeError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Raised when the type of a dataset prevents some action.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

DependencyCheckError

DependencyCheckError(checker_path_str, original_exception)

Bases: ModelRunnerError

Error occurred within a dependency checker function itself.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, checker_path_str: str, original_exception: Exception):
    message = f"Error in dependency checker '{checker_path_str}'"
    super().__init__(message, original_exception)
    self.checker_path_str = checker_path_str

DependencyError

DependencyError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Raised when optional dependencies are missing.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

DependencyNotMetError

DependencyNotMetError(
    model_name, dependency_type, silent, details=None
)

Bases: ModelRunnerError

A required dependency for a model was not met. If this was a non-silent dependency, ModelRunner.run() will propagate this error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    model_name: str,
    dependency_type: str,
    silent: bool,
    details: str | None = None,
):
    base_message = f"Dependency '{dependency_type}' not met for model '{model_name}'"
    if details:
        base_message += f": {details}"
    message = f"{base_message} (Silent: {silent})"
    super().__init__(message)
    self.model_name = model_name
    self.dependency_type = dependency_type
    self.silent = silent

DorsalClientError

DorsalClientError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Dorsal Python client error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.message = message
    self.request_url = request_url
    self.original_exception = original_exception

DorsalConfigError

DorsalConfigError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Config (dorsal.toml) error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

DorsalError

DorsalError(
    message, request_url=None, original_exception=None
)

Bases: Exception

Base class for all custom exceptions raised by the Dorsal library.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

DuplicateFileError

DuplicateFileError(message, file_paths=None)

Bases: DorsalError

Duplicate file error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message, file_paths: list[str] | None = None):
    super().__init__(message)
    self.file_paths = file_paths

DuplicateTagError

DuplicateTagError(message)

Bases: TaggingError

A duplicate tag exists.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str):
    super().__init__(message)

FileAnnotatorError

FileAnnotatorError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Base exception for all errors originating from the FileAnnotator.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

ForbiddenError

ForbiddenError(
    message, request_url=None, response_text=None
)

Bases: DorsalClientError

403 Forbidden error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    response_text: str | None = None,
):
    self.request_url = request_url
    self.response_text = response_text
    full_message = f"{message}" if request_url else message
    super().__init__(full_message)

InvalidTagError

InvalidTagError(message)

Bases: TaggingError

Tag is invalid.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str):
    super().__init__(message)

MissingHashError

MissingHashError(message, original_exception=None)

Bases: ModelRunnerError

A required hash (e.g., validation hash) was not found after base model processing.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, original_exception: Exception | None = None):
    super().__init__(message)
    self.original_exception = original_exception

ModelExecutionError

ModelExecutionError(
    model_name, file_path, original_exception
)

Bases: ModelRunnerError

Error during the execution of an individual annotation model's 'main' method.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, model_name: str, file_path: str, original_exception: Exception):
    message = f"Error executing model '{model_name}' for file '{file_path}'"
    super().__init__(message, original_exception)
    self.model_name = model_name
    self.file_path = file_path

ModelImportError

ModelImportError(callable_path_str, original_exception)

Bases: ModelRunnerError

Errors that occur when trying to import a model or its validator.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, callable_path_str: str, original_exception: Exception):
    message = f"Failed to import '{callable_path_str}'"
    super().__init__(message, original_exception)
    self.callable_path_str = callable_path_str

ModelOutputValidationError

ModelOutputValidationError(
    model_name, validator_name, errors, original_exception
)

Bases: ModelRunnerError

Error when a model's output fails Pydantic validation.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    model_name: str,
    validator_name: str,
    errors: list[Any],
    original_exception: Exception | None,
):
    message = f"Output from model '{model_name}' failed validation against '{validator_name}'"
    super().__init__(message, original_exception)
    self.model_name = model_name
    self.validator_name = validator_name
    self.validation_errors = errors

ModelRunnerConfigError

ModelRunnerConfigError(message, original_exception=None)

Bases: ModelRunnerError

Errors related to loading or validating the ModelRunner pipeline configuration.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, original_exception: Exception | None = None):
    super().__init__(message)
    self.original_exception = original_exception

ModelRunnerError

ModelRunnerError(message, original_exception=None)

Bases: DorsalError

Base class for errors specific to the ModelRunner.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, original_exception: Exception | None = None):
    super().__init__(message)
    self.original_exception = original_exception

NetworkError

NetworkError(
    message, request_url=None, original_exception=None
)

Bases: DorsalClientError

Network error e.g. timeout or other connectivity issues.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

NotFoundError

NotFoundError(
    message, request_url=None, response_text=None
)

Bases: DorsalClientError

404 Not Found error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    response_text: str | None = None,
):
    self.request_url = request_url
    self.response_text = response_text
    super().__init__(f"{message}")

NotPopulatedError

NotPopulatedError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Indicates data is incomplete.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

PDFProcessingError

PDFProcessingError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Raised when PDF processing fails (corruption, password protection, etc.).

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

PipelineIntegrityError

PipelineIntegrityError(message, original_exception=None)

Bases: ModelRunnerError

Error indicating an unexpected state or structure in the pipeline results during merging.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, original_exception: Exception | None = None):
    super().__init__(message)
    self.original_exception = original_exception

QuickHashConfigurationError

QuickHashConfigurationError(message, file_path=None)

Bases: QuickHasherError, ValueError

Error related to QuickHasher internal configuration.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, file_path: str | None = None):
    super().__init__(message)
    self.file_path = file_path
    self.message = message

QuickHashFileInstabilityError

QuickHashFileInstabilityError(message, file_path=None)

Bases: QuickHasherError

Error indicating the file changed or was inconsistent during hashing.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, file_path: str | None = None):
    super().__init__(message)
    self.file_path = file_path
    self.message = message

QuickHashFileSizeError

QuickHashFileSizeError(message, file_path=None)

Bases: QuickHasherError, ValueError

Error for file size being outside permitted QuickHasher range when configured to raise.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, file_path: str | None = None):
    super().__init__(message)
    self.file_path = file_path
    self.message = message

QuickHasherError

QuickHasherError(message, file_path=None)

Bases: DorsalError

Base class for errors specific to QuickHasher operations.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, file_path: str | None = None):
    super().__init__(message)
    self.file_path = file_path
    self.message = message

RateLimitError

RateLimitError(
    message,
    request_url,
    retry_after=None,
    response_text=None,
)

Bases: DorsalClientError

429 Too Many Requests error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str,
    retry_after: str | int | None = None,
    response_text: str | None = None,
):
    self.request_url = request_url
    self.retry_after = retry_after
    self.response_text = response_text
    super_message = f"{message} for {request_url}"
    if retry_after:
        super_message += f". Try again after {retry_after} seconds."
    super().__init__(super_message)

ReadError

ReadError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Read error.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

RecordValidationError

RecordValidationError(
    message, dataset_id, validation_summary=None
)

Bases: ValidationError

Indicates records failed client-side validation against the dataset's schema.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str, dataset_id: str, validation_summary: dict | None = None):
    super().__init__(message)
    self.dataset_id = dataset_id
    self.validation_summary = validation_summary

SchemaFormatError

SchemaFormatError(
    message,
    schema_error_detail=None,
    original_exception=None,
)

Bases: ValidationError

Indicates that a JSON schema document is structurally invalid or unprocessable.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    schema_error_detail: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.schema_error_detail = schema_error_detail
    self.original_exception = original_exception

SyncConflictError

SyncConflictError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Raised when a sync operation is blocked because the remote collection has changed since the last synchronization.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

TaggingError

TaggingError(message)

Bases: ValidationError

Error tagging a file.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(self, message: str):
    super().__init__(message)

TemplateNotFoundError

TemplateNotFoundError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Raised when a report template or its essential files cannot be found.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

UnexpectedResponseError

UnexpectedResponseError(
    message, request_url=None, original_exception=None
)

Bases: DorsalClientError

The API returned an unexpected response.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.message = message
    self.request_url = request_url
    self.original_exception = original_exception

UnsupportedHashError

UnsupportedHashError(
    message, request_url=None, original_exception=None
)

Bases: ValidationError

Unsupported file hash.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception

ValidationError

ValidationError(
    message, request_url=None, original_exception=None
)

Bases: DorsalError

Base validation error class.

Source code in venv/lib/python3.13/site-packages/dorsal/common/exceptions.py

def __init__(
    self,
    message: str,
    request_url: str | None = None,
    original_exception: Exception | None = None,
):
    super().__init__(message)
    self.request_url = request_url
    self.original_exception = original_exception