Exceptions¶

exceptions ¶

Classes¶

BoxlabError ¶

BoxlabError(message: str | None = None)

Bases: Exception

Base exception for all Boxlab-related errors.

This is the root exception class for the Boxlab library. All custom exceptions in Boxlab inherit from this class, making it easy to catch any Boxlab-specific error.

Each exception has an associated error code for programmatic error handling and a default message that can be overridden.

Attributes:

Name	Type	Description
`default_message`	`str`	Default error message for this exception type.
`code`	`int`	Unique error code identifying this exception type.
`message`		The actual error message for this instance.

Example

from boxlab.exceptions import BoxlabError

try:
    # Some Boxlab operation
    pass
except BoxlabError as e:
    print(f"Boxlab error occurred: {e}")
    print(f"Error code: {e.code}")

Example

# Create custom exception
class CustomError(BoxlabError):
    default_message = "Custom error occurred"
    code = 999


raise CustomError("Something went wrong")

Initialize the exception.

Parameters:

Name	Type	Description	Default
`message`	`str \| None`	Custom error message. If None, uses default_message.	`None`

Source code in boxlab/exceptions.py

def __init__(self, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        message: Custom error message. If None, uses default_message.
    """
    self.message = message or self.default_message
    super().__init__(message)

Functions¶

str ¶

__str__() -> str

Return formatted error string with code.

Returns:

Type	Description
`str`	Formatted string in the form "[Error {code}] {message}".

Source code in boxlab/exceptions.py

def __str__(self) -> str:
    """Return formatted error string with code.

    Returns:
        Formatted string in the form "[Error {code}] {message}".
    """
    return f"[Error {self.code}] {self.message}"

repr ¶

__repr__() -> str

Return detailed representation of the exception.

Returns:

Type	Description
`str`	String showing class name, code, and message.

Source code in boxlab/exceptions.py

def __repr__(self) -> str:
    """Return detailed representation of the exception.

    Returns:
        String showing class name, code, and message.
    """
    return f"{self.__class__.__name__}(code={self.code}, message={self.message!r})"

RequiredModuleNotFoundError ¶

RequiredModuleNotFoundError(*module_name: str, message: str | None = None)

Bases: BoxlabError

Exception raised when a required module is not found.

This exception is raised when attempting to use functionality that requires optional dependencies (e.g., torch, torchvision, PIL) that are not installed.

Attributes:

Name	Type	Description
`default_message`		Template for the default error message.
`code`	`int`	Error code 2.
`module_name`		Tuple of missing module names.

Example

from boxlab.exceptions import RequiredModuleNotFoundError

try:
    from boxlab.dataset.torchadapter import (
        build_torchdataset,
    )
except RequiredModuleNotFoundError as e:
    print(f"Missing modules: {e.module_name}")
    print(
        "Install with: pip install torch torchvision pillow"
    )

Example

# Raise for multiple missing modules
raise RequiredModuleNotFoundError(
    "torch",
    "torchvision",
    message="PyTorch packages required",
)

Initialize the exception.

Parameters:

Name	Type	Description	Default
`*module_name`	`str`	One or more names of missing modules.	`()`
`message`	`str \| None`	Custom error message. If None, uses formatted default_message.	`None`

Source code in boxlab/exceptions.py

def __init__(self, *module_name: str, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        *module_name: One or more names of missing modules.
        message: Custom error message. If None, uses formatted default_message.
    """
    self.module_name = module_name
    full_message = message or self.default_message.format(module_name=module_name)
    super().__init__(full_message)

Functions¶

repr ¶

__repr__() -> str

Return detailed representation of the exception.

Returns:

Type	Description
`str`	String showing class name, module names, and message.

Source code in boxlab/exceptions.py

def __repr__(self) -> str:
    """Return detailed representation of the exception.

    Returns:
        String showing class name, module names, and message.
    """
    return (
        f"{self.__class__.__name__}(module_name={self.module_name!r}, message={self.message!r})"
    )

DatasetError ¶

DatasetError(message: str | None = None)

Bases: BoxlabError

Base exception for dataset-related errors.

This is the base class for all dataset operation errors. Catch this exception to handle any dataset-related issue.

Attributes:

Name	Type	Description
`default_message`		Default error message.
`code`	`int`	Error code 10.

Example

from boxlab.exceptions import DatasetError

try:
    dataset.some_operation()
except DatasetError as e:
    print(f"Dataset operation failed: {e}")

Source code in boxlab/exceptions.py

def __init__(self, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        message: Custom error message. If None, uses default_message.
    """
    self.message = message or self.default_message
    super().__init__(message)

DatasetNotFoundError ¶

DatasetNotFoundError(path: str, message: str | None = None)

Bases: DatasetError

Exception raised when a dataset is not found.

Raised when attempting to load or access a dataset that doesn't exist at the specified path.

Attributes:

Name	Type	Description
`default_message`		Template for the default error message.
`code`	`int`	Error code 11.
`path`		The path where the dataset was expected.

Example

from boxlab.exceptions import DatasetNotFoundError
from boxlab.dataset.io import load_dataset

try:
    dataset = load_dataset("/nonexistent/path")
except DatasetNotFoundError as e:
    print(f"Dataset not found at: {e.path}")

Example

# Raise with custom message
raise DatasetNotFoundError(
    "/data/missing.json",
    message="COCO annotations file not found",
)

Initialize the exception.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path where the dataset was expected.	required
`message`	`str \| None`	Custom error message. If None, uses formatted default_message.	`None`

Source code in boxlab/exceptions.py

def __init__(self, path: str, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        path: The path where the dataset was expected.
        message: Custom error message. If None, uses formatted default_message.
    """
    self.path = path
    full_message = message or self.default_message.format(path=path)
    super().__init__(full_message)

Functions¶

DatasetFormatError ¶

DatasetFormatError(format: str, message: str | None = None)

Bases: DatasetError

Exception raised for invalid dataset format.

Raised when a dataset file or structure doesn't match the expected format, or when the format is not recognized.

Attributes:

Name	Type	Description
`default_message`		Template for the default error message.
`code`	`int`	Error code 12.
`format`		The format that caused the error.

Example

from boxlab.exceptions import DatasetFormatError
from boxlab.dataset.io import load_dataset

try:
    dataset = load_dataset("data.txt", format="unknown")
except DatasetFormatError as e:
    print(f"Invalid format: {e.format}")

Example

# Raise for malformed JSON
raise DatasetFormatError(
    "coco",
    message="COCO JSON missing required 'images' field",
)

Initialize the exception.

Parameters:

Name	Type	Description	Default
`format`	`str`	The format identifier that caused the error.	required
`message`	`str \| None`	Custom error message. If None, uses formatted default_message.	`None`

Source code in boxlab/exceptions.py

def __init__(self, format: str, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        format: The format identifier that caused the error.
        message: Custom error message. If None, uses formatted default_message.
    """
    self.format = format
    full_message = message or self.default_message.format(format=format)
    super().__init__(full_message)

Functions¶

DatasetLoadError ¶

DatasetLoadError(reason: str, message: str | None = None)

Bases: DatasetError

Exception raised when dataset loading fails.

Raised when an error occurs during the dataset loading process, such as corrupted files, parsing errors, or I/O failures.

Attributes:

Name	Type	Description
`default_message`		Template for the default error message.
`code`	`int`	Error code 13.
`reason`		Description of why loading failed.

Example

from boxlab.exceptions import DatasetLoadError
from boxlab.dataset.io import load_dataset

try:
    dataset = load_dataset("corrupted.json")
except DatasetLoadError as e:
    print(f"Load failed: {e.reason}")

Example

# Raise for parsing error
raise DatasetLoadError(
    reason="JSON parse error at line 42",
    message="Failed to parse COCO annotations",
)

Initialize the exception.

Parameters:

Name	Type	Description	Default
`reason`	`str`	Description of why loading failed.	required
`message`	`str \| None`	Custom error message. If None, uses formatted default_message.	`None`

Source code in boxlab/exceptions.py

def __init__(self, reason: str, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        reason: Description of why loading failed.
        message: Custom error message. If None, uses formatted default_message.
    """
    self.reason = reason
    full_message = message or self.default_message.format(reason=reason)
    super().__init__(full_message)

Functions¶

DatasetExportError ¶

DatasetExportError(reason: str, message: str | None = None)

Bases: DatasetError

Exception raised when dataset export fails.

Raised when an error occurs during dataset export, such as I/O failures, permission errors, or format conversion issues.

Attributes:

Name	Type	Description
`default_message`		Template for the default error message.
`code`	`int`	Error code 14.
`reason`		Description of why export failed.

Example

from boxlab.exceptions import DatasetExportError
from boxlab.dataset.io import export_dataset

try:
    export_dataset(dataset, "/readonly/path", format="coco")
except DatasetExportError as e:
    print(f"Export failed: {e.reason}")

Example

# Raise for permission error
raise DatasetExportError(
    reason="Permission denied",
    message="Cannot write to output directory",
)

Initialize the exception.

Parameters:

Name	Type	Description	Default
`reason`	`str`	Description of why export failed.	required
`message`	`str \| None`	Custom error message. If None, uses formatted default_message.	`None`

Source code in boxlab/exceptions.py

def __init__(self, reason: str, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        reason: Description of why export failed.
        message: Custom error message. If None, uses formatted default_message.
    """
    self.reason = reason
    full_message = message or self.default_message.format(reason=reason)
    super().__init__(full_message)

Functions¶

DatasetMergeError ¶

DatasetMergeError(reason: str, message: str | None = None)

Bases: DatasetError

Exception raised when dataset merge fails.

Raised when an error occurs during dataset merging operations, such as incompatible datasets or merge conflicts.

Attributes:

Name	Type	Description
`default_message`		Template for the default error message.
`code`	`int`	Error code 15.
`reason`		Description of why merge failed.

Example

from boxlab.exceptions import DatasetMergeError
from boxlab.dataset.io import merge

try:
    merged = merge()  # No datasets provided
except DatasetMergeError as e:
    print(f"Merge failed: {e.reason}")

Example

# Raise for incompatible datasets
raise DatasetMergeError(
    reason="Incompatible category structures",
    message="Cannot merge datasets with different category schemas",
)

Initialize the exception.

Parameters:

Name	Type	Description	Default
`reason`	`str`	Description of why merge failed.	required
`message`	`str \| None`	Custom error message. If None, uses formatted default_message.	`None`

Source code in boxlab/exceptions.py

def __init__(self, reason: str, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        reason: Description of why merge failed.
        message: Custom error message. If None, uses formatted default_message.
    """
    self.reason = reason
    full_message = message or self.default_message.format(reason=reason)
    super().__init__(full_message)

Functions¶

CategoryConflictError ¶

CategoryConflictError(category_name: str, message: str | None = None)

Bases: DatasetError

Exception raised when category conflicts occur.

Raised during dataset merging when category names conflict and the conflict resolution strategy is set to 'error'.

Attributes:

Name	Type	Description
`default_message`		Template for the default error message.
`code`	`int`	Error code 16.
`category_name`		The category name that caused the conflict.

Example

from boxlab.exceptions import CategoryConflictError
from boxlab.dataset.io import merge

try:
    merged = merge(ds1, ds2, resolve_conflicts="error")
except CategoryConflictError as e:
    print(f"Category conflict: {e.category_name}")

Example

# Raise for duplicate category
raise CategoryConflictError(
    "person",
    message="Category 'person' exists with different IDs",
)

Initialize the exception.

Parameters:

Name	Type	Description	Default
`category_name`	`str`	The category name that caused the conflict.	required
`message`	`str \| None`	Custom error message. If None, uses formatted default_message.	`None`

Source code in boxlab/exceptions.py

def __init__(self, category_name: str, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        category_name: The category name that caused the conflict.
        message: Custom error message. If None, uses formatted default_message.
    """
    self.category_name = category_name
    full_message = message or self.default_message.format(category_name=category_name)
    super().__init__(full_message)

Functions¶

ValidationError ¶

ValidationError(reason: str, message: str | None = None)

Bases: BoxlabError

Exception raised for validation errors.

Raised when data fails validation checks, such as invalid split ratios, malformed bounding boxes, or constraint violations.

Attributes:

Name	Type	Description
`default_message`		Template for the default error message.
`code`	`int`	Error code 20.
`reason`		Description of what failed validation.

Example

from boxlab.exceptions import ValidationError
from boxlab.dataset.types import SplitRatio

try:
    split = SplitRatio(0.5, 0.3, 0.1)
    split.validate()
except ValidationError as e:
    print(f"Validation failed: {e.reason}")

Example

# Raise for invalid bbox
raise ValidationError(
    reason="x_max must be greater than x_min",
    message="Invalid bounding box coordinates",
)

Initialize the exception.

Parameters:

Name	Type	Description	Default
`reason`	`str`	Description of what failed validation.	required
`message`	`str \| None`	Custom error message. If None, uses formatted default_message.	`None`

Source code in boxlab/exceptions.py

def __init__(self, reason: str, message: str | None = None) -> None:
    """Initialize the exception.

    Args:
        reason: Description of what failed validation.
        message: Custom error message. If None, uses formatted default_message.
    """
    self.reason = reason
    full_message = message or self.default_message.format(reason=reason)
    super().__init__(full_message)

Functions¶

options: show_root_heading: true show_source: true heading_level: 2 members_order: source show_signature_annotations: true separate_signature: true

Overview¶

BoxLab uses a hierarchical exception system for clear and specific error handling. All exceptions inherit from BoxlabError, making it easy to catch all BoxLab-specific errors or handle specific error types.

Each exception has:

A unique error code for programmatic handling
A default message template
Additional context attributes relevant to the error type

Exception Hierarchy¶

BoxlabError (code: 1)
├── RequiredModuleNotFoundError (code: 2)
├── DatasetError (code: 10)
│   ├── DatasetNotFoundError (code: 11)
│   ├── DatasetFormatError (code: 12)
│   ├── DatasetLoadError (code: 13)
│   ├── DatasetExportError (code: 14)
│   ├── DatasetMergeError (code: 15)
│   └── CategoryConflictError (code: 16)
└── ValidationError (code: 20)

Error Codes¶

Error codes can be used for programmatic error handling:

Code	Exception	Category
1	BoxlabError	Base
2	RequiredModuleNotFoundError	Dependencies
10	DatasetError	Dataset (base)
11	DatasetNotFoundError	Dataset I/O
12	DatasetFormatError	Dataset Format
13	DatasetLoadError	Dataset Loading
14	DatasetExportError	Dataset Export
15	DatasetMergeError	Dataset Merge
16	CategoryConflictError	Dataset Merge
20	ValidationError	Validation

Exceptions¶

exceptions ¶

Classes¶

BoxlabError ¶

Functions¶

__str__ ¶

__repr__ ¶

RequiredModuleNotFoundError ¶

Functions¶

__repr__ ¶

DatasetError ¶

DatasetNotFoundError ¶

Functions¶

DatasetFormatError ¶

Functions¶

DatasetLoadError ¶

Functions¶

DatasetExportError ¶

Functions¶

DatasetMergeError ¶

Functions¶

CategoryConflictError ¶

Functions¶

ValidationError ¶

Functions¶

Overview¶

Exception Hierarchy¶

Error Codes¶

See Also¶

str ¶

repr ¶

repr ¶