Reference Guide

en_exceptions

This library provides exception classes that can be used to report and handle errors in Envase applications and services. At the root, the library provides base classes that applications and services should use to implement more concrete types of errors.

The library also provides concrete implementations of errors that are common for most applications and services. These error classes are provided in separate modules in the library that need to be explicitely imported.

Base Exceptions

en_exceptions.base

This module provides base classes for most common types of exceptions. Applications should provide their own exception classes by deriving from the most concrete exception provided by this module.

Important

The classes in this module are exposed at the root package of the library; therefore, applications, services, and other libraries don’t need to import this module directly and instead, they should import en_exceptions.

import en_exceptions as exc

class CustomError(exc.SerializableError):
    def __init__(self, custom_parameter, message=None):
        super().__init__(message or f'Custom message for {custom_parameter}')
        self.custom_parameter = custom_parameter

    def _add_data(self, serialized):
        serialized.update(custom_parameter=self.custom_parameter)

Important

Many times we have the tendency of deriving exception types directly from SerializableError. Although all Envase exception types in this library derive ultimately from SerializableError, custom exception classes should select a more suitable base class for two reasons.

First, there might be functionality on other base classes that you can leverage on your own exceptions. Second, we can build exception functionality over time by providing additional base classes on this library.

This can also allow us to extend the functionality of exception objects in a more cohesive way insuring concrete classes also leverage that functionality.

exception InvalidInputError(pname, invalid_value, message=None)

Exception representing an input error. The exception is initialized with the name of the attribute, property, or parameter with the invalid value, and the invalid value that caused the exception. Applications and services can derive from this class to represent more concrete input errors.

Parameters

• pname (str) – Name of the attribute, property, or parameter for which an invalid value was specified.

• value (any) – Invalid value specified that caused the exception.

exception RequiredInputError(pname, message=None)

Exception representing and erro from a required attribute, property, or parameter missing from the input. Applications and services can derive from this class to represent more concrete required input errors.

Parameters

pname (str) – Name of the required attribute, property, or parameter that is missing from the input.

exception SerializableError(message)

Base class for all the exceptions. Every exception class provided in applications and libraries must, ultimately, derived from this class, but best practices recommend to derived from a more concrete exception type.

to_dict()

Overrides the Serializable interface to inject the message property.

Returns

A dictionary representation of the exception.

Return type

dict

exception UnknownError(original_exception, message=None)

This exception wraps another exception when an unknown error is raised. It allows exceptions caused by other libraries for unknown reasons to be wrapped into the Serializable interface. The exception provides the original traceback as part of the data.

Parameters

original_exception (Exception) – The original exception raised.

exception UnsupportedOperationError(operation, class_name, message=None)

This exception represents an error calling an interface that is not supported by a class. Sometimes, a class needs to implement an interface but it cannot implement all the methods. This exception should be used to indicate the methods that are not supported.

Important

This does not substitute the NotImplementedError exception to indicate that a method is abstract and not implemented in the base class.

Common Application Errors

en_exceptions.application

This module provides concrete exception classes that are commonly used in Envase applications, services, and libraries. The classes in this module are not intended for extension (you should not derive from them); instead, they should be used directly to insure consistency among all applications and services.

exception ClientError(response, message=None)

This exception represents a client error response where the status code is in the 4xx range. Applications, services, and libraries should use this exception to be more concrete than a ResponseError.

exception InvalidEnvironmentError(environment)

This exception should be raised to indicate that the identifier of an environment is invalid. Most applications and services are executed in some sort of environment (dev, stg, prd). The environment might allow different functionality and this can be enabled through some sort of configuration file or an environment variable.

If the configuration or environment variable is not properly configured, applications and services should raise this exception should be used to indicate it. The following snippet illustrates this concept.

import en_exceptions.application as eapp

def create_service(environment):
    if environment == 'prd': return PrdService()
    if environment == 'stg': return StgService()
    if environment == 'dev': return DevService()
    raise eapp.InvalidEnvironmentError(environment)

# In application code
#
config = get_config()
environment = config.get('ENVIRONMENT')
service = create_service(environment)

In the example, the application retrieves the environment identifier from the configuration. If someone has mistyped, the environment identifier, we want to know right away.

The create_service() function returns the correct service; unless, the environment identifier is not understood, in which case it raises an InvalidEnvironmentError.

exception ResponseError(response, message=None)

This exception should be raised to represent an HTTP error when calling another service. The exception wraps a response object and exposes the status_code and contents of the response as the exception information.

When the response object contains JSON as the body, the exception will expose the JsonObject as the info attribute. Responses that don’t contain JSON are converted using the text as the value of the body property of the JsonObject.

Parameters

• response (Response) – Response that indicates an error from a service request.

• message (str) – Optional message to describe the exception.

The following example shows how to use this exception:

import requests
import en_exceptions.application as apperrors

url = 'https://some.url.com/api'
response = request.get(url)
if response.status_code != 200
    raise apperrors.ResponseError(response)

The application can raise the exception to indicate the error response and insure the data from the response is maintained.

exception ServerError(response, message=None)

This exception represents a server error response where the status code is in the 5xx range. Applications, services, and libraries should use this exception to be more concrete than a ResponseError.