pumpwood_communication.exceptions

  1"""Define PumpWood exceptions to be treated as API errors.
  2
  3Define specific errors for the PumpWood platform. These errors are handled
  4explicitly and do not result in default 500 responses.
  5"""
  6from typing import Any
  7from loguru import logger
  8
  9
 10class PumpWoodException(Exception): # NOQA
 11    """Special exception used in PumpWood systems.
 12
 13    It permits handling raises in applications by serializing responses
 14    with ``to_dict`` and exposing the HTTP status as ``status_code``.
 15    """
 16
 17    status_code: int = 400
 18    """PumpWoodException will return status 400 on Pumpwood backend."""
 19
 20    message: str
 21    """Message associated with raise."""
 22
 23    payload: dict
 24    """Dictionary payload returned by ``to_dict`` and used to format
 25       the message string."""
 26
 27    i8n_object: None
 28    """I8n object used to translate the message."""
 29
 30    was_translated: bool
 31    """If the message was translated."""
 32
 33    tag: str
 34    """Tag used to disambiguate translation context."""
 35
 36    parallel: bool
 37    """If error was raised on a parallel request."""
 38
 39    def __repr__(self):
 40        """@private."""
 41        message_fmt = self.format_message()
 42        template = "{class_name}[status_code={status_code}]: " + \
 43            "{message_fmt}\nerror payload={payload}"
 44        return template.format(
 45            class_name=self.__class__.__name__,
 46            status_code=self.status_code,
 47            message_fmt=message_fmt,
 48            payload=self.payload)
 49
 50    def __str__(self):
 51        """@private."""
 52        message_fmt = self.format_message()
 53        template = "{class_name}[status_code={status_code}]: " + \
 54            "{message_fmt}\nerror payload={payload}"
 55        return template.format(
 56            class_name=self.__class__.__name__,
 57            status_code=self.status_code,
 58            message_fmt=message_fmt,
 59            payload=self.payload)
 60
 61    def __init__(self, message: str, payload: dict = None,
 62                 status_code: int = None, tag: str = '',
 63                 parallel: bool = False, i8n_object: None = None,
 64                 was_translated: bool = False):
 65        """Initialize the PumpWood exception.
 66
 67        Args:
 68            message (str):
 69                Message formatted with payload data using ``{key}``
 70                placeholders.
 71            payload (dict):
 72                Payload data passed as a dictionary. Returned in
 73                ``to_dict`` and used to format the message.
 74                Defaults to None.
 75            status_code (int):
 76                HTTP status code override. Defaults to None.
 77            i8n_object (None):
 78                I8n object used to translate the message.
 79                Defaults to None.
 80            tag (str):
 81                Tag used to disambiguate translation context.
 82                Defaults to empty string.
 83            parallel (bool):
 84                Whether the error occurred during parallel work.
 85                Defaults to False.
 86        """
 87        Exception.__init__(self)
 88
 89        # Initialize payload to avoid mutable default issues
 90        if payload is None:
 91            payload = {}
 92
 93        self.message = message
 94        if status_code is not None:
 95            self.status_code = status_code
 96        self.payload = payload
 97        self.i8n_object = i8n_object
 98        self.was_translated = was_translated
 99        self.tag = tag
100        self.parallel = parallel
101
102    def format_message(self) -> str:
103        """Format exception message using payload data.
104
105        Substitute placeholders at exception message with payload.
106
107        Returns:
108            str:
109                Message with placeholders substituted from payload data.
110        """
111        try:
112            # If i8n_object is not None and was_translated is False,
113            # use it to translate the message
114            message = self.message
115            if (self.i8n_object is not None) and (not self.was_translated):
116                message = self.i8n_object.t(
117                    sentence=self.message, tag=self.tag)
118            return message.format(**self.payload)
119        except Exception:
120            return self.message + "\n** format error **"
121
122    def to_dict(self) -> dict[str, Any]:
123        """Serialize exception object for API response.
124
125        Returns:
126            dict[str, Any]:
127                Dictionary with keys:
128            - **payload [dict]:** Payload associated with the raise.
129            - **type [str]:** Name of the exception class.
130            - **message_not_fmt [str]:** Message without payload
131                substitution.
132            - **message [str]:** Message formatted with payload data.
133            - **status_code [int]:** HTTP status code for the exception.
134            - **translate [bool]:** Whether the message should be
135                translated.
136            - **tag [str]:** Tag used to disambiguate translation
137                context.
138            - **parallel [bool]:** Whether the error was from parallel
139                work.
140        """
141        message_fmt = self.format_message()
142        rv = {
143            "__error__": 'PumpWoodException',
144            "type": self.__class__.__name__,
145            "payload": self.payload,
146            "message_not_fmt": self.message,
147            "message": message_fmt,
148            "status_code": self.status_code,
149            "was_translated": self.was_translated,
150            "tag": self.tag,
151            "parallel": self.parallel}
152        return rv
153
154
155class PumpWoodDataLoadingException(PumpWoodException):
156    """Problem when loading data at dataloaders and to_load models."""
157
158    pass
159
160
161class PumpWoodDatabaseError(PumpWoodException):
162    """Errors raised by Postgres and not treated by other handlers."""
163
164    pass
165
166
167class PumpWoodUniqueDatabaseError(PumpWoodException):
168    """Unique errors raised by Postgres."""
169
170    pass
171
172
173class PumpWoodDataTransformationException(PumpWoodException):
174    """Problem when transforming model data."""
175
176    pass
177
178
179class PumpWoodWrongParameters(PumpWoodException):
180    """Invalid or missing request parameters."""
181
182    pass
183
184
185class PumpWoodObjectSavingException(PumpWoodException):
186    """Problem when saving object data."""
187
188    pass
189
190
191class PumpWoodObjectDeleteException(PumpWoodException):
192    """Problem when deleting object data."""
193
194    pass
195
196
197class PumpWoodActionArgsException(PumpWoodException):
198    """Missing arguments to perform action."""
199
200    pass
201
202
203class PumpWoodUnauthorized(PumpWoodException):
204    """User is unauthorized to perform the action."""
205
206    status_code = 401
207
208
209class PumpWoodForbidden(PumpWoodException):
210    """Action is not permitted."""
211
212    status_code = 403
213
214
215class PumpWoodObjectDoesNotExist(PumpWoodException):
216    """Object not found in database."""
217
218    status_code = 404
219
220
221class PumpWoodQueryException(PumpWoodException):
222    """Problem when querying data, like wrong fields or operators."""
223
224    pass
225
226
227class PumpWoodIntegrityError(PumpWoodException):
228    """Problem when saving data due to IntegrityError."""
229
230    pass
231
232
233class PumpWoodNotImplementedError(PumpWoodException):
234    """Feature or operation is not implemented."""
235
236    pass
237
238
239class PumpWoodMicroserviceUnavailableError(PumpWoodException):
240    """Microservice is unavailable or was not deployed."""
241
242    pass
243
244
245class PumpWoodMFAError(PumpWoodException):
246    """Problem when using MFA."""
247
248    pass
249
250
251class PumpWoodJSONLoadError(PumpWoodException):
252    """Problem loading JSON data from a request."""
253
254    pass
255
256
257class PumpWoodCacheError(PumpWoodException):
258    """Problem using the PumpWood cache."""
259
260    pass
261
262
263class PumpWoodOtherException(PumpWoodException):
264    """Unhandled or unmapped server error."""
265
266    status_code = 500
267
268    def __init__(self, message: str, payload: dict = None,
269                 status_code: int = None, was_translated: bool = False,
270                 tag: str = '', parallel: bool = False):
271        """Initialize PumpWoodOtherException.
272
273        Args:
274            message (str):
275                Message formatted with payload data using ``{key}``
276                placeholders. Truncated to 1000 characters.
277            payload (dict):
278                Payload data passed as a dictionary. Returned in
279                ``to_dict`` and used to format the message.
280                Defaults to None.
281            was_translated (bool):
282                If the message was translated. Defaults to False.
283            tag (str):
284                Tag used to disambiguate translation context.
285                Defaults to empty string.
286            status_code (int):
287                Change the default status code of the exception.
288                Defaults to None.
289            parallel (bool):
290                Whether the error occurred during parallel work.
291                Defaults to False.
292        """
293        Exception.__init__(self)
294
295        # Initialize payload to avoid mutable default issues
296        if payload is None:
297            payload = {}
298
299        # Limit size of the error, it is expected that other exceptions
300        # may have long text from kong or other between services
301        self.message = message[:1000]
302
303        if status_code is not None:
304            self.status_code = status_code
305        self.payload = payload
306
307        # Other exceptions are never translated are never translated
308        self.was_translated = False
309        self.tag = tag
310        self.parallel = parallel
311
312    def format_message(self) -> str:
313        """Return the message without formatting.
314        
315        Other exceptions are never translated, so the message is not formatted
316        and returned as is.
317        """
318        return self.message
319    
320
321class AirflowMicroServiceException(PumpWoodException):
322    """Exception raised from AirflowMicroService."""
323
324    pass
325
326
327exceptions_dict = {
328    "PumpWoodException": PumpWoodException,
329    "PumpWoodDataLoadingException": PumpWoodDataLoadingException,
330    "PumpWoodDatabaseError": PumpWoodDatabaseError,
331    "PumpWoodDataTransformationException": PumpWoodDataTransformationException,
332    "PumpWoodWrongParameters": PumpWoodWrongParameters,
333    "PumpWoodObjectSavingException": PumpWoodObjectSavingException,
334    "PumpWoodObjectDeleteException": PumpWoodObjectDeleteException,
335    "PumpWoodActionArgsException": PumpWoodActionArgsException,
336    "PumpWoodUnauthorized": PumpWoodUnauthorized,
337    "PumpWoodForbidden": PumpWoodForbidden,
338    "PumpWoodObjectDoesNotExist": PumpWoodObjectDoesNotExist,
339    "PumpWoodQueryException": PumpWoodQueryException,
340    "PumpWoodIntegrityError": PumpWoodIntegrityError,
341    "PumpWoodNotImplementedError": PumpWoodNotImplementedError,
342    "PumpWoodMicroserviceUnavailableError":
343        PumpWoodMicroserviceUnavailableError,
344    "PumpWoodMFAError": PumpWoodMFAError,
345    "PumpWoodJSONLoadError": PumpWoodJSONLoadError,
346    "PumpWoodCacheError": PumpWoodCacheError,
347    "PumpWoodOtherException": PumpWoodOtherException,
348    "AirflowMicroServiceException": AirflowMicroServiceException,
349    "PumpWoodUniqueDatabaseError": PumpWoodUniqueDatabaseError
350}
351"""
352Dictionary mapping exception class names to types.
353
354Used by backends and microservices to re-raise PumpWood exceptions.
355"""
356
357
358def raise_pumpwood_exception(exception_name: str, message: str,
359                             payload: dict = None, status_code: int = None,
360                             translate: bool = False, tag: str = '',
361                             parallel: bool = False):
362    """Raise a PumpWood exception based on its name.
363
364    Args:
365        exception_name (str):
366            Name of the exception to be retrieved and raised.
367        message (str):
368            The error message associated with the exception.
369        payload (dict):
370            A dictionary containing additional data for the exception.
371            Defaults to None.
372        status_code (int):
373            HTTP status code to be returned. Defaults to None.
374        translate (bool):
375            Whether the message should be translated. Defaults to False.
376        tag (str):
377            Tag used to disambiguate translation context.
378            Defaults to empty string.
379        parallel (bool):
380            If the exception happened during parallel processing.
381            Defaults to False.
382
383    Returns:
384        None:
385            This function does not return; it always raises an exception.
386
387    Raises:
388        PumpWoodOtherException:
389            If ``exception_name`` is not found in the registry.
390        PumpWoodException:
391            The specific exception mapped to ``exception_name``.
392    """
393    # Initialize payload to avoid mutable default issues
394    if payload is None:
395        payload = {}
396
397    pumpwood_exception = exceptions_dict.get(exception_name)
398    if pumpwood_exception is None:
399        msg = (
400            "exception_name [{exception_name}] not found in PumpWood "
401            "Exceptions. Check implementation")
402        logger.error(
403            msg.format(exception_name=exception_name))
404        raise PumpWoodOtherException(
405            msg.format(exception_name=exception_name),
406            payload=payload, status_code=status_code,
407            tag=tag, parallel=parallel)
408    else:
409        raise pumpwood_exception(
410            message=message, payload=payload, status_code=status_code,
411            translate=translate, tag=tag, parallel=parallel)
412
413
414def raise_from_dict(exception_dict: dict):
415    """Raise a PumpWood exception from a serialized error dict.
416
417    Accepts output from `PumpWoodException.to_dict()` or compatible
418    payloads using `type` as the exception class name.
419
420    Args:
421        exception_dict (dict):
422            Serialized exception data. Expected keys are `type` (or
423            legacy `exception_name`), `message_not_fmt`, `payload`,
424            `status_code`, `translate`, `tag`, and `parallel`.
425
426    Returns:
427        None:
428            This function does not return as it always raises an
429            exception.
430
431    Raises:
432        PumpWoodOtherException:
433            If the specified exception type is not found in the
434            registry.
435        PumpWoodException:
436            The specific exception mapped to the exception type.
437    """
438    exception_name = exception_dict.get("type") or exception_dict.get(
439        "exception_name")
440    message_not_fmt = exception_dict.get("message_not_fmt")
441    payload = exception_dict.get("payload")
442    status_code = exception_dict.get("status_code")
443    translate = exception_dict.get("translate", False)
444    tag = exception_dict.get("tag", '')
445    parallel = exception_dict.get("parallel", False)
446
447    raise_pumpwood_exception(
448        exception_name=exception_name,
449        message=message_not_fmt, payload=payload, status_code=status_code,
450        translate=translate, tag=tag, parallel=parallel)