pip_services3_commons.errors package
Submodules
- pip_services3_commons.errors.ApplicationException module
- pip_services3_commons.errors.ApplicationExceptionFactory module
- pip_services3_commons.errors.BadRequestException module
- pip_services3_commons.errors.ConfigException module
- pip_services3_commons.errors.ConflictException module
- pip_services3_commons.errors.ConnectionException module
- pip_services3_commons.errors.ErrorCategory module
- pip_services3_commons.errors.ErrorDescription module
- pip_services3_commons.errors.ErrorDescriptionFactory module
- pip_services3_commons.errors.FileException module
- pip_services3_commons.errors.InternalException module
- pip_services3_commons.errors.InvalidStateException module
- pip_services3_commons.errors.InvocationException module
- pip_services3_commons.errors.NotFoundException module
- pip_services3_commons.errors.UnauthorizedException module
- pip_services3_commons.errors.UnknownException module
- pip_services3_commons.errors.UnsupportedException module
Module contents
pip_services3_commons.errors.__init__
Portable and localizable Exceptions classes. Each Exception, in addition to a description and stack trace has a unique string code, details array (which can be used for creating localized strings).
Way to use: - An existing error class can be used. - A child class that extends ApplicationException can we written. - A error can be wrapped around (into?) an existing application error.
Exceptions are serializable. The error classes themselves are not serializable, but they can be converted to ErrorDescriptions, which are serializable in one language, transferred to the receiving side, and deserialized in another language. After deserialization, the initial error class can be restored.
Additionally: when transferring an error from one language to another, the error type that is closest to the initial error type is chosen from the exceptions available in the target language.
- copyright
Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.
- license
MIT, see LICENSE for more details.
-
exception
pip_services3_commons.errors.
ApplicationException
(category: str = 'Unknown', correlation_id: Optional[str, None] = None, code: str = 'UNKNOWN', message: str = 'Unknown error') Bases:
Exception
Defines a base class to defive various application exceptions.
Most languages have own definition of base error (error) types. However, this class is implemented symmetrically in all languages supported by PipServices toolkit. It allows to create portable implementations and support proper error propagation in microservices calls.
Error propagation means that when microservice implemented in one language calls microservice(s) implemented in a different language(s), errors are returned throught the entire call chain and restored in their original (or close) type.
Since number of potential error types is endless, PipServices toolkit supports only 12 standard categories of exceptions defined in
ErrorCategory
. ThisApplicationException
class acts as a basis for all obj 12 standard error types.Most exceptions have just free-form message that describes occured error. That may not be sufficient to create meaninful error descriptions. The
ApplicationException
class proposes an extended error definition that has more standard fields: - message: is a human-readable error description - category: one of 12 standard error categories of errors - status: numeric HTTP status code for REST invocations - code: a unique error code, usually defined as “MY_ERROR_CODE” - correlation_id: a unique transaction id to trace execution through a call chain - details: map with error parameters that can help to recreate meaningful error description in obj languages - stack_trace: a stack trace - cause: original error that is wrapped by this errorApplicationException class is not serializable. To pass errors through the wire it is converted into
ErrorDescription
<pip_services3_commons.errors.ErrorDescription.ErrorDescription>` object and restored on receiving end into identical error type.-
get_cause_string
() → str Gets original error wrapped by this error as a string message.
- Returns
an original error message.
-
get_stack_trace_string
() → Optional[str, None] Gets a stack trace where this error occured.
- Returns
a stack trace as a string.
-
set_cause_string
(value: str) Sets original error wrapped by this error as a string message.
- Parameters
value – an original error message.
-
set_stack_trace_string
(value: str) Sets a stack trace where this error occured.
- Parameters
value – a stack trace as a string
-
to_json
()
-
with_cause
(cause: Exception) → pip_services3_commons.errors.ApplicationException.ApplicationException Sets a original error wrapped by this error
This method returns reference to this error to implement Builder pattern to chain additional calls.
- Parameters
cause – original error object
- Returns
this error object
-
with_code
(code: str) → pip_services3_commons.errors.ApplicationException.ApplicationException Sets a unique error code. This method returns reference to this error to implement Builder pattern to chain additional calls.
- Parameters
code – a unique error code
- Returns
this error object
-
with_correlation_id
(correlation_id: Optional[str, None]) → pip_services3_commons.errors.ApplicationException.ApplicationException Sets a correlation id which can be used to trace this error through a call chain.
This method returns reference to this error to implement Builder pattern to chain additional calls.
- Parameters
correlation_id – a unique transaction id to trace error through call chain
- Returns
this error object
-
with_details
(key: str, value: Any) → pip_services3_commons.errors.ApplicationException.ApplicationException Sets a parameter for additional error details. This details can be used to restore error description in obj languages.
This method returns reference to this error to implement Builder pattern to chain additional calls.
- Parameters
key – a details parameter name
value – a details parameter name
- Returns
this error object
-
with_stack_trace
(stack_trace: str) → pip_services3_commons.errors.ApplicationException.ApplicationException Sets a stack trace for this error.
This method returns reference to this error to implement Builder pattern to chain additional calls.
- Parameters
stack_trace – a stack trace where this error occured
- Returns
this error object
-
with_status
(status: int) → pip_services3_commons.errors.ApplicationException.ApplicationException Sets a HTTP status code which shall be returned by REST calls. This method returns reference to this error to implement Builder pattern to chain additional calls.
- Parameters
status – an HTTP error code.
- Returns
this error object
-
wrap
(cause: Any) → pip_services3_commons.errors.ApplicationException.ApplicationException Wraps another error into an application error object.
If original error is of ApplicationException type it is returned without changes. Otherwise a new ApplicationException is created and original error is set as its cause.
- Parameters
cause – an original error object
- Returns
an original or newly created ApplicationException
-
static
wrap_error
(error: pip_services3_commons.errors.ApplicationException.ApplicationException, cause: Any) → pip_services3_commons.errors.ApplicationException.ApplicationException Wraps another exception into specified application exception object.
If original exception is of ApplicationException type it is returned without changes. Otherwise the original error is set as a cause to specified ApplicationException object.
- Parameters
error – an ApplicationException object to wrap the cause
cause – an original error object
- Returns
an original or newly created ApplicationException
-
-
class
pip_services3_commons.errors.
ApplicationExceptionFactory
Bases:
object
Factory to recreate exceptions from
ErrorDescription
values passed through the wire.-
static
create
(description: pip_services3_commons.errors.ErrorDescription.ErrorDescription) → pip_services3_commons.errors.ApplicationException.ApplicationException Recreates ApplicationException object from serialized ErrorDescription.
It tries to restore original error type using type or error category fields.
- Parameters
description – a serialized error description received as a result of remote call
- Returns
ApplicationException object from serialized ErrorDescription.
-
static
-
exception
pip_services3_commons.errors.
BadRequestException
(correlation_id: Optional[str, None] = None, code: str = None, message: str = None) Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Errors due to improper user requests.
-
exception
pip_services3_commons.errors.
ConfigException
(correlation_id: Optional[str, None] = None, code: str = None, message: str = None) Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Errors related to mistakes in the microservice’s user-defined configurations.
-
exception
pip_services3_commons.errors.
ConflictException
(correlation_id: Optional[str, None] = None, code: str = None, message: str = None) Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Errors raised by conflicts between object versions that were posted by the user and those that are stored on the server.
-
exception
pip_services3_commons.errors.
ConnectionException
(correlation_id: Optional[str, None] = None, code: str = None, message: str = None) Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Errors happened during connection to remote services. They can be related to misconfiguration, network issues or remote service itself
-
class
pip_services3_commons.errors.
ErrorCategory
Bases:
object
Defines standard error categories to application exceptions supported by PipServices toolkit.
-
BadRequest
: str = 'BadRequest' Errors due to improper user requests, like missing or wrong parameters
-
Conflict
: str = 'Conflict' Errors raised by conflict in object versions posted by user and stored on server.
-
FailedInvocation
: str = 'FailedInvocation' Errors returned by remote services or network during call attempts
-
InvalidState
: str = 'InvalidState' Errors related to operations called in wrong component state. For instance, business calls when component is not ready
-
Misconfiguration
: str = 'Misconfiguration' Errors related to mistakes in user-defined configuration
-
NoResponse
: str = 'NoResponse' Errors happened during connection to remote services. They can be related to misconfiguration, network issues or remote service itself
Access errors caused by missing user identity or security permissions
-
-
class
pip_services3_commons.errors.
ErrorDescription
Bases:
object
Serializeable error description. It is use to pass information about errors between microservices implemented in different languages. On the receiving side
ErrorDescription
is used to recreate error object close to its original type without missing additional details.
-
class
pip_services3_commons.errors.
ErrorDescriptionFactory
Bases:
object
Factory to create serializeable
ErrorDescription
fromApplicationException
or from arbitrary errors.The ErrorDescriptions are used to pass errors through the wire between microservices implemented in different languages. They allow to restore exceptions on the receiving side close to the original type and preserve additional information.
-
static
create
(ex: Any) → pip_services3_commons.errors.ErrorDescription.ErrorDescription Creates a serializable ErrorDescription from error object.
- Parameters
ex – an error object
- Returns
a serializeable ErrorDescription object that describes the error.
-
static
-
exception
pip_services3_commons.errors.
FileException
(correlation_id: Optional[str, None] = None, code: str = None, message: str = None) Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Errors in read/write local disk operations.
-
exception
pip_services3_commons.errors.
InternalException
(correlation_id: Optional[str, None] = None, code: str = None, message: str = None) Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Errors caused by programming mistakes
-
exception
pip_services3_commons.errors.
InvalidStateException
(correlation_id: Optional[str, None] = None, code: str = None, message: str = None) Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Errors related to calling operations, which require the component to be in a specific state.
For instance, business calls when component is not ready
-
exception
pip_services3_commons.errors.
InvocationException
(correlation_id: Optional[str, None] = None, code: str = None, message: str = None) Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Errors returned by remote services or by the network during call attempts.
-
exception
pip_services3_commons.errors.
NotFoundException
(correlation_id: Optional[str, None] = None, code: str = None, message: str = None) Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Error caused by attempt to access missing object
Bases:
pip_services3_commons.errors.ApplicationException.ApplicationException
Access errors caused by missing user identity (authentication error) or incorrect security permissions (authorization error).