Skip to content

Cache Exceptions API

Exception classes specific to the cache module with structured error metadata.

Base Cache Exception

CacheException

CacheException

Bases: JPYCacheError

Base cache exception with structured context.

Source code in src/jinpy_utils/cache/exceptions.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
class CacheException(JPYCacheError):
    """Base cache exception with structured context."""

    def __init__(  # noqa: PLR0913
        self,
        message: str,
        *,
        error_code: str = "CACHE_ERROR",
        operation: CacheOperation | None = None,
        error_type: CacheErrorType = CacheErrorType.OPERATION,
        cache_key: str | None = None,
        backend_name: str | None = None,
        backend_type: str | None = None,
        **kwargs: Any,
    ) -> None:
        details = kwargs.pop("details", {})
        if operation:
            details["operation"] = operation.value
        if error_type:
            details["error_type"] = error_type.value
        if cache_key:
            details["cache_key"] = cache_key
        if backend_name:
            details["backend_name"] = backend_name
        if backend_type:
            details["backend_type"] = backend_type

        super().__init__(
            message=message,
            cache_key=cache_key,
            cache_backend=backend_name or backend_type,
            operation=operation.value if operation else None,
            details=details,
            suggestions=kwargs.pop(
                "suggestions",
                [
                    "Check cache backend connectivity",
                    "Verify cache key format",
                    "Ensure sufficient memory/storage",
                    "Check cache backend configuration",
                ],
            ),
            **kwargs,
        )
        self.operation = operation
        self.error_type = error_type
        self.backend_name = backend_name
        self.backend_type = backend_type

Functions

__init__ 

__init__(
    message: str,
    *,
    error_code: str = "CACHE_ERROR",
    operation: CacheOperation | None = None,
    error_type: CacheErrorType = OPERATION,
    cache_key: str | None = None,
    backend_name: str | None = None,
    backend_type: str | None = None,
    **kwargs: Any
) -> None
Source code in src/jinpy_utils/cache/exceptions.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def __init__(  # noqa: PLR0913
    self,
    message: str,
    *,
    error_code: str = "CACHE_ERROR",
    operation: CacheOperation | None = None,
    error_type: CacheErrorType = CacheErrorType.OPERATION,
    cache_key: str | None = None,
    backend_name: str | None = None,
    backend_type: str | None = None,
    **kwargs: Any,
) -> None:
    details = kwargs.pop("details", {})
    if operation:
        details["operation"] = operation.value
    if error_type:
        details["error_type"] = error_type.value
    if cache_key:
        details["cache_key"] = cache_key
    if backend_name:
        details["backend_name"] = backend_name
    if backend_type:
        details["backend_type"] = backend_type

    super().__init__(
        message=message,
        cache_key=cache_key,
        cache_backend=backend_name or backend_type,
        operation=operation.value if operation else None,
        details=details,
        suggestions=kwargs.pop(
            "suggestions",
            [
                "Check cache backend connectivity",
                "Verify cache key format",
                "Ensure sufficient memory/storage",
                "Check cache backend configuration",
            ],
        ),
        **kwargs,
    )
    self.operation = operation
    self.error_type = error_type
    self.backend_name = backend_name
    self.backend_type = backend_type

Specific Cache Exceptions

CacheConfigurationError

CacheConfigurationError

Bases: CacheException

Configuration related cache errors.

Source code in src/jinpy_utils/cache/exceptions.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
class CacheConfigurationError(CacheException):
    """Configuration related cache errors."""

    def __init__(
        self,
        message: str,
        *,
        config_section: str | None = None,
        config_value: str | None = None,
        **kwargs: Any,
    ) -> None:
        details = kwargs.pop("details", {})
        if config_section:
            details["config_section"] = config_section
        if config_value is not None:
            details["config_value"] = config_value
        super().__init__(
            message=message,
            error_code="CACHE_CONFIGURATION_ERROR",
            operation=kwargs.pop("operation", None),
            error_type=CacheErrorType.CONFIGURATION,
            details=details,
            **kwargs,
        )

Functions

__init__ 

__init__(
    message: str,
    *,
    config_section: str | None = None,
    config_value: str | None = None,
    **kwargs: Any
) -> None
Source code in src/jinpy_utils/cache/exceptions.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def __init__(
    self,
    message: str,
    *,
    config_section: str | None = None,
    config_value: str | None = None,
    **kwargs: Any,
) -> None:
    details = kwargs.pop("details", {})
    if config_section:
        details["config_section"] = config_section
    if config_value is not None:
        details["config_value"] = config_value
    super().__init__(
        message=message,
        error_code="CACHE_CONFIGURATION_ERROR",
        operation=kwargs.pop("operation", None),
        error_type=CacheErrorType.CONFIGURATION,
        details=details,
        **kwargs,
    )

CacheConnectionError

CacheConnectionError

Bases: CacheException

Connection/availability issues with remote cache services.

Source code in src/jinpy_utils/cache/exceptions.py 
85
86
87
88
89
90
91
92
93
94
class CacheConnectionError(CacheException):
    """Connection/availability issues with remote cache services."""

    def __init__(self, message: str, **kwargs: Any) -> None:
        super().__init__(
            message=message,
            error_code="CACHE_CONNECTION_ERROR",
            error_type=CacheErrorType.CONNECTION,
            **kwargs,
        )

Functions

__init__ 

__init__(message: str, **kwargs: Any) -> None
Source code in src/jinpy_utils/cache/exceptions.py 
88
89
90
91
92
93
94
def __init__(self, message: str, **kwargs: Any) -> None:
    super().__init__(
        message=message,
        error_code="CACHE_CONNECTION_ERROR",
        error_type=CacheErrorType.CONNECTION,
        **kwargs,
    )

CacheSerializationError

CacheSerializationError

Bases: CacheException

Serialization/deserialization failures.

Source code in src/jinpy_utils/cache/exceptions.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
class CacheSerializationError(CacheException):
    """Serialization/deserialization failures."""

    def __init__(
        self, message: str, *, cache_key: str | None = None, **kwargs: Any
    ) -> None:
        super().__init__(
            message=message,
            error_code="CACHE_SERIALIZATION_ERROR",
            operation=kwargs.pop("operation", None),
            error_type=CacheErrorType.SERIALIZATION,
            cache_key=cache_key,
            **kwargs,
        )

Functions

__init__ 

__init__(message: str, *, cache_key: str | None = None, **kwargs: Any) -> None
Source code in src/jinpy_utils/cache/exceptions.py 
100
101
102
103
104
105
106
107
108
109
110
def __init__(
    self, message: str, *, cache_key: str | None = None, **kwargs: Any
) -> None:
    super().__init__(
        message=message,
        error_code="CACHE_SERIALIZATION_ERROR",
        operation=kwargs.pop("operation", None),
        error_type=CacheErrorType.SERIALIZATION,
        cache_key=cache_key,
        **kwargs,
    )

CacheKeyError

CacheKeyError

Bases: CacheException

Invalid or missing cache key errors.

Source code in src/jinpy_utils/cache/exceptions.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
class CacheKeyError(CacheException):
    """Invalid or missing cache key errors."""

    def __init__(
        self, message: str, *, cache_key: str | None = None, **kwargs: Any
    ) -> None:
        super().__init__(
            message=message,
            error_code="CACHE_KEY_ERROR",
            operation=kwargs.pop("operation", None),
            error_type=CacheErrorType.KEY_ERROR,
            cache_key=cache_key,
            **kwargs,
        )

Functions

__init__ 

__init__(message: str, *, cache_key: str | None = None, **kwargs: Any) -> None
Source code in src/jinpy_utils/cache/exceptions.py 
116
117
118
119
120
121
122
123
124
125
126
def __init__(
    self, message: str, *, cache_key: str | None = None, **kwargs: Any
) -> None:
    super().__init__(
        message=message,
        error_code="CACHE_KEY_ERROR",
        operation=kwargs.pop("operation", None),
        error_type=CacheErrorType.KEY_ERROR,
        cache_key=cache_key,
        **kwargs,
    )

CacheTimeoutError

CacheTimeoutError

Bases: CacheException

Cache operation timeouts.

Source code in src/jinpy_utils/cache/exceptions.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
class CacheTimeoutError(CacheException):
    """Cache operation timeouts."""

    def __init__(
        self,
        message: str,
        *,
        timeout_seconds: float | None = None,
        **kwargs: Any,
    ) -> None:
        details = kwargs.pop("details", {})
        if timeout_seconds is not None:
            details["timeout_seconds"] = timeout_seconds
        super().__init__(
            message=message,
            error_code="CACHE_TIMEOUT_ERROR",
            operation=kwargs.pop("operation", None),
            error_type=CacheErrorType.TIMEOUT,
            details=details,
            **kwargs,
        )

Functions

__init__ 

__init__(
    message: str, *, timeout_seconds: float | None = None, **kwargs: Any
) -> None
Source code in src/jinpy_utils/cache/exceptions.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def __init__(
    self,
    message: str,
    *,
    timeout_seconds: float | None = None,
    **kwargs: Any,
) -> None:
    details = kwargs.pop("details", {})
    if timeout_seconds is not None:
        details["timeout_seconds"] = timeout_seconds
    super().__init__(
        message=message,
        error_code="CACHE_TIMEOUT_ERROR",
        operation=kwargs.pop("operation", None),
        error_type=CacheErrorType.TIMEOUT,
        details=details,
        **kwargs,
    )

CacheBackendError

CacheBackendError

Bases: CacheException

Backend-specific failures.

Source code in src/jinpy_utils/cache/exceptions.py 
152
153
154
155
156
157
158
159
160
161
class CacheBackendError(CacheException):
    """Backend-specific failures."""

    def __init__(self, message: str, **kwargs: Any) -> None:
        super().__init__(
            message=message,
            error_code="CACHE_BACKEND_ERROR",
            error_type=CacheErrorType.BACKEND_ERROR,
            **kwargs,
        )

Functions

__init__ 

__init__(message: str, **kwargs: Any) -> None
Source code in src/jinpy_utils/cache/exceptions.py 
155
156
157
158
159
160
161
def __init__(self, message: str, **kwargs: Any) -> None:
    super().__init__(
        message=message,
        error_code="CACHE_BACKEND_ERROR",
        error_type=CacheErrorType.BACKEND_ERROR,
        **kwargs,
    )

Usage Examples

Handling configuration errors

from jinpy_utils.cache import CacheManager, CacheManagerConfig, CacheConfigurationError

try:
    CacheManager(CacheManagerConfig(backends=[]))
except CacheConfigurationError as e:
    print("Config error:", e.message)

Handling backend errors

from jinpy_utils.cache import Cache, CacheBackendError

cache = Cache()
try:
    cache.set("k", object())  # may fail for selected serializer
except CacheBackendError as e:
    print("Backend error:", e.message)