Coverage for src / ezpl / core / exceptions.py: 100.00%

1# /////////////////////////////////////////////////////////////// 

2# EZPL - Core Exceptions 

3# Project: ezpl 

4# /////////////////////////////////////////////////////////////// 

5 

6""" 

7Core exceptions for Ezpl logging framework. 

8 

9This module defines all custom exceptions used throughout the application 

10with detailed error codes for better error tracking and diagnosis. 

11""" 

12 

13from __future__ import annotations 

14 

15# /////////////////////////////////////////////////////////////// 

16# IMPORTS 

17# /////////////////////////////////////////////////////////////// 

18# Standard library imports 

19# (No standard library imports needed for this module) 

20 

21# /////////////////////////////////////////////////////////////// 

22# CLASSES 

23# /////////////////////////////////////////////////////////////// 

24 

25 

26class EzplError(Exception): 

27 """ 

28 Base exception class for all Ezpl-related errors. 

29 

30 All custom exceptions in the Ezpl framework inherit from this base class, 

31 enabling centralized exception handling and consistent error reporting. 

32 Each exception includes a message and optional error code for categorization. 

33 """ 

34 

35 # /////////////////////////////////////////////////////////////// 

36 # INIT 

37 # /////////////////////////////////////////////////////////////// 

38 

39 def __init__(self, message: str, error_code: str | None = None) -> None: 

40 """ 

41 Initialize the Ezpl error. 

42 

43 Args: 

44 message: Human-readable error message 

45 error_code: Optional error code for categorization and debugging 

46 

47 Note: 

48 Error codes follow the pattern: COMPONENT_ERROR or OPERATION_ERROR 

49 (e.g., "CONFIG_ERROR", "FILE_ERROR") for consistent error tracking. 

50 """ 

51 super().__init__(message) 

52 self.message = message 

53 self.error_code = error_code 

54 

55 # /////////////////////////////////////////////////////////////// 

56 # REPRESENTATION METHODS 

57 # /////////////////////////////////////////////////////////////// 

58 

59 def __str__(self) -> str: 

60 """String representation of the error.""" 

61 if self.error_code: 

62 return f"[{self.error_code}] {self.message}" 

63 return self.message 

64 

65 

66class ConfigurationError(EzplError): 

67 """ 

68 Exception raised for configuration-related errors. 

69 

70 This exception is raised when configuration loading, validation, or processing 

71 encounters issues. The optional config_key attribute helps identify which 

72 configuration parameter caused the problem. 

73 """ 

74 

75 # /////////////////////////////////////////////////////////////// 

76 # INIT 

77 # /////////////////////////////////////////////////////////////// 

78 

79 def __init__(self, message: str, config_key: str | None = None) -> None: 

80 """ 

81 Initialize the configuration error. 

82 

83 Args: 

84 message: Human-readable error message 

85 config_key: Optional configuration key that caused the error 

86 """ 

87 super().__init__(message, "CONFIG_ERROR") 

88 self.config_key = config_key 

89 

90 

91class LoggingError(EzplError): 

92 """ 

93 Exception raised for logging-related errors. 

94 

95 This exception covers issues with logging operations such as file writing, 

96 format processing, or handler initialization. The optional handler_type 

97 attribute identifies which handler (console, file) caused the error. 

98 """ 

99 

100 # /////////////////////////////////////////////////////////////// 

101 # INIT 

102 # /////////////////////////////////////////////////////////////// 

103 

104 def __init__(self, message: str, handler_type: str | None = None) -> None: 

105 """ 

106 Initialize the logging error. 

107 

108 Args: 

109 message: Human-readable error message 

110 handler_type: Optional handler type that caused the error (e.g., "file", "console") 

111 """ 

112 super().__init__(message, "LOGGING_ERROR") 

113 self.handler_type = handler_type 

114 

115 

116class ValidationError(EzplError): 

117 """ 

118 Exception raised for validation errors. 

119 

120 This exception is raised when input validation fails (e.g., invalid log levels, 

121 malformed configuration values). The optional field_name and value attributes 

122 help identify what was being validated when the error occurred. 

123 """ 

124 

125 # /////////////////////////////////////////////////////////////// 

126 # INIT 

127 # /////////////////////////////////////////////////////////////// 

128 

129 def __init__( 

130 self, message: str, field_name: str | None = None, value: str | None = None 

131 ) -> None: 

132 """ 

133 Initialize the validation error. 

134 

135 Args: 

136 message: Human-readable error message 

137 field_name: Optional field name that failed validation 

138 value: Optional value that failed validation 

139 """ 

140 super().__init__(message, "VALIDATION_ERROR") 

141 self.field_name = field_name 

142 self.value = value 

143 

144 

145class InitializationError(EzplError): 

146 """ 

147 Exception raised for initialization errors. 

148 

149 This exception is raised when Ezpl components fail to initialize properly. 

150 The optional component attribute identifies which component (printer, logger, config) 

151 encountered the initialization issue. 

152 """ 

153 

154 # /////////////////////////////////////////////////////////////// 

155 # INIT 

156 # /////////////////////////////////////////////////////////////// 

157 

158 def __init__(self, message: str, component: str | None = None) -> None: 

159 """ 

160 Initialize the initialization error. 

161 

162 Args: 

163 message: Human-readable error message 

164 component: Optional component that failed to initialize 

165 """ 

166 super().__init__(message, "INIT_ERROR") 

167 self.component = component 

168 

169 

170class FileOperationError(EzplError): 

171 """ 

172 Exception raised for file operation errors. 

173 

174 This exception covers issues with file operations (reading, writing, creating files). 

175 The optional file_path and operation attributes help identify which file and 

176 operation (read, write, create) failed. 

177 """ 

178 

179 # /////////////////////////////////////////////////////////////// 

180 # INIT 

181 # /////////////////////////////////////////////////////////////// 

182 

183 def __init__( 

184 self, message: str, file_path: str | None = None, operation: str | None = None 

185 ) -> None: 

186 """ 

187 Initialize the file operation error. 

188 

189 Args: 

190 message: Human-readable error message 

191 file_path: Optional file path that caused the error 

192 operation: Optional operation that failed (e.g., "read", "write", "create") 

193 """ 

194 super().__init__(message, "FILE_ERROR") 

195 self.file_path = file_path 

196 self.operation = operation 

197 

198 

199class HandlerError(EzplError): 

200 """ 

201 Exception raised for handler-related errors. 

202 

203 This exception covers issues with logging handlers (initialization, configuration, 

204 operation failures). The optional handler_name attribute identifies which handler 

205 (EzPrinter, EzLogger) caused the problem. 

206 """ 

207 

208 # /////////////////////////////////////////////////////////////// 

209 # INIT 

210 # /////////////////////////////////////////////////////////////// 

211 

212 def __init__(self, message: str, handler_name: str | None = None) -> None: 

213 """ 

214 Initialize the handler error. 

215 

216 Args: 

217 message: Human-readable error message 

218 handler_name: Optional handler name that caused the error 

219 """ 

220 super().__init__(message, "HANDLER_ERROR") 

221 self.handler_name = handler_name