Exceptions

This module provides specific exception classes for nested dictionaries. These exceptions extend the standard Exception, KeyError and AttributeError classes to provide more context and better error handling for nested dictionary operations.

All exceptions inherit from StackedDictionaryError, which itself inherits from Exception. Specialisations also inherit from the matching standard library exception so that standard except clauses continue to work:

try:
    nd["missing_key"]
except KeyError:        # catches StackedKeyError too
    ...
except StackedKeyError: # catches only StackedKeyError
    ...

Base exception

exception ndict_tools.StackedDictionaryError(message: str | None = None, error_code: int = 0, path: list[Any] | None = None)

Bases: Exception

Base exception class for all stacked dictionary errors.

This is the parent class for all exceptions related to stacked dictionaries. It provides context about the error including an optional error code.

Initialize a StackedDictionaryError.

Parameters:

  • message (str) – A message describing the error.

  • error_code (int) – An integer code identifying the error type.

  • path (list[Any]) – The path in the nested dictionary where the error occurred.

Specialisations

exception ndict_tools.StackedKeyError(message: str | None = None, key: Any | None = None, path: list[Any] | None = None)

Bases: KeyError, StackedDictionaryError

Exception raised when a key operation fails in a stacked dictionary.

This exception is raised for key-related errors such as missing keys, invalid key types, or operations that cannot be performed on certain keys.

Initialize a StackedKeyError.

Parameters:

  • message (str) – A message describing the error.

  • key (Any) – The key that caused the error.

  • path (list[Any]) – The path in the nested dictionary where the error occurred.

exception ndict_tools.StackedAttributeError(message: str | None = None, attribute: str | None = None, path: list[Any] | None = None)

Bases: AttributeError, StackedDictionaryError

Exception raised when an attribute operation fails in a stacked dictionary.

This exception is raised when attempting to access or modify attributes that don’t exist or cannot be modified in the current context.

Initialize a StackedAttributeError.

Parameters:

  • message (str) – A message describing the error.

  • attribute (str) – The attribute that caused the error.

  • path (list[Any]) – The path in the nested dictionary where the error occurred.

exception ndict_tools.StackedTypeError(message: str | None = None, expected_type: type | None = None, actual_type: type | None = None, path: list[Any] | None = None)

Bases: TypeError, StackedDictionaryError

Exception raised when a type error occurs in a stacked dictionary operation.

This exception is raised when an operation receives an argument of the wrong type, such as using nested lists as keys or attempting to perform operations on incompatible types.

Initialize a StackedTypeError.

Parameters:

  • message (str) – A message describing the error.

  • expected_type (type | None) – The expected type for the operation.

  • actual_type (type | None) – The actual type that was provided.

  • path (list[Any]) – The path in the nested dictionary where the error occurred.

exception ndict_tools.StackedValueError(message: str | None = None, value: Any | None = None, path: list[Any] | None = None)

Bases: ValueError, StackedDictionaryError

Exception raised when a value error occurs in a stacked dictionary operation.

This exception is raised when an operation receives a value that is semantically inappropriate, such as a value that cannot be found in the dictionary.

Initialize a StackedValueError.

Parameters:

  • message (str) – A message describing the error.

  • value (Any) – The value that caused the error.

  • path (list[Any]) – The path in the nested dictionary where the error occurred.

exception ndict_tools.StackedIndexError(message: str | None = None, path: list[Any] | None = None)

Bases: IndexError, StackedDictionaryError

Exception raised when an index error occurs in a stacked dictionary operation.

This exception is raised when attempting to access an empty dictionary or when an operation cannot be performed due to the dictionary being empty.

Initialize a StackedIndexError.

Parameters:

  • message (str) – A message describing the error.

  • path (list[Any]) – The path in the nested dictionary where the error occurred.

exception ndict_tools.NestedDictionaryException(message: str | None = None, error_code: int = 0, path: list[Any] | None = None)

Bases: StackedDictionaryError

General exception for nested dictionary operations.

This exception is raised when a nested dictionary operation fails but doesn’t fall into a more specific error category.

Initialize a NestedDictionaryException.

Parameters:

  • message (str) – A message describing the error.

  • error_code (int) – An integer code identifying the error type.

  • path (list[Any]) – The path in the nested dictionary where the error occurred.