The grpc_error_interpretation.py module

Summary

Exceptions

UnexpectedEngineError	Raised if an error that is unexpected for the call is made.
EngineDisconnectedError	Raised if the ModelCenter service is not available.
InvalidInstanceError	Raised if the target element ID is no longer valid.
ValueOutOfRangeError	Raised if an argument value is out of range.

Functions

interpret_rpc_error

Decorate a function so that the grpc.RpcErrors that it raises are

Constants

WRAP_NAME_COLLISION	Pass this to wrap_rpcerror to wrap ALREADY_EXISTS as a
WRAP_TARGET_NOT_FOUND	Pass this to wrap_rpcerror when NOT_FOUND indicates that the calling
WRAP_INVALID_ARG	Pass this to wrap_rpcerror when responsibility for invalid arguments is
WRAP_OUT_OF_BOUNDS	Pass this to the wrap_rpcerror when the responsibility for out-of-range

Description

Defines the decorator and standard exception types.

The decorator and exceptons types interpret errors from the gRPC client.

Module detail

grpc_error_interpretation.interpret_rpc_error(additional_codes: Mapping[grpc.StatusCode, Type[Exception]] = {})

Decorate a function so that the grpc.RpcErrors that it raises are wrapped in a more meaningful way.

By default, the status codes UNAVAILABLE and INTERNAL are mapped to EngineDisconnectedError and EngineInternalError. Callers can specify additional mappings in the additional_codes parameter. The key should be the status code, and the value should be the exception type. The type should take a single parameter in its constructor that is the message from the gRPC error.

Take care when specifying additional codes to ensure that the wrapped gRPC call is supposed to raise the code in question for a particular reason. This module also supplies some predefined maps that represent commonplace mappings between gRPC error codes and exception types. These are not universally applicable, but they can be passed to the decorator when appropriate for the gRPC call in question. Remember that you can create a merged dictionary on the fly with the following syntax:

{\**DICT_ONE, \**DICT_TWO, additional_key: additional_value}

If a code is not specified (or is one of the default codes), it is wrapped as an UnexpectedEngineError.

Parameters:

additional_codesMapping[grpc.StatusCode, Type[Exception]]

Map of additional codes to wrap.

grpc_error_interpretation.WRAP_NAME_COLLISION: Mapping[grpc.StatusCode, Type[Exception]]

Pass this to wrap_rpcerror to wrap ALREADY_EXISTS as a NameCollisionError.

Do not attempt to modify this map.

grpc_error_interpretation.WRAP_TARGET_NOT_FOUND: Mapping[grpc.StatusCode, Type[Exception]]

Pass this to wrap_rpcerror when NOT_FOUND indicates that the calling instance is invalid.

Do not attempt to modify this map.

grpc_error_interpretation.WRAP_INVALID_ARG: Mapping[grpc.StatusCode, Type[Exception]]

Pass this to wrap_rpcerror when responsibility for invalid arguments is the caller’s.

Note that this is not always the case. For example, sometimes the arguments passed to the gRPC method are entirely calculated by the API, and there is no way for the user to cause it to produce invalid arguments. In this case, you should wrap this code as an internal error.

Do not attempt to modify this map.

grpc_error_interpretation.WRAP_OUT_OF_BOUNDS: Mapping[grpc.StatusCode, Type[Exception]]

Pass this to the wrap_rpcerror when the responsibility for out-of-range arguments is the caller’s.

Note that this is not always the case. For example, sometimes the arguments passed to the gRPC method are entirely calculated by the API, and there is no way for the user to cause it to produce invalid arguments. In this case, you should wrap this code as an internal error.

Do not attempt to modify this map.