ubii.framework.errors module

To get specific errors to raise for the different errors the master node can send during communication with a client node this module defines some new Exception types that also inherit from ubii.proto.Error and rules for the proto.marshal.Marshal for serialization of these Exceptions on the fly.

Importing this module registers the rules for the marshal of the ubii.proto module to convert between the Error protobuf messages (internally used by the ubii.proto.Error wrapper) and the new UbiiError exception type i.e. when this module is imported Error protobuf messages will not be converted to plain ubii.proto.Error wrapper objects, but instead to UbiiError objects so that they can be used in a The raise statement expression. Depending on e.g. the value if the ubii.proto.Error.title subtypes of UbiiError might be used, i.e. it’s possible to differentiate the type of error in an The try statement statement.

Example

A short overview of the proto-plus marshaling process (since it’s not documented in detail):

Get the marshal name used in your proto-plus module, in this case

import ubii.proto
marshal_name = ubii.proto.__protobuf__.marshal

Get a reference to the marshal by name (same name returns same object, see documentation of proto.marshal.Marshal)

import proto.marshal
marshal = proto.marshal.Marshal(name=marshal_name)

Create a rule – you can use the existing rules of the proto-plus package as a starting point

from proto.marshal.rules.message import MessageRule
class CustomRule(MessageRule):
    def to_proto(self, value):
        # convert wrapper to actual protobuf message type and return it
        ...

    def to_python(self, value, *, absent: bool | None = None):
        # convert actual protobuf message to python wrapper and return it,
        ...

Register the rule at the Marshal you retrieved earlier. To do that you need the actual protobuf type that you want to handle with the rule, if you only got proto-plus wrappers at your disposal, you need to first get the internal type from the wrapper

Error_pb = ubii.proto.Error.pb()  # actual protobuf type created for the Error wrapper
marshal.register(Error_pb, CustomRule(descriptor=Error_pb, wrapper=ubii.proto.Error))

See also

proto.marshal.Marshal – documentation of the Marshal class in the proto-plus module.

ubii.proto.__protobuf__ – module level variable of the ubii-msg-formats module to expose the proto-plus marshal and message pool

exception ubii.framework.errors.UbiiError(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: Error, Exception

Base class for all custom errors.

title

Field of type STRING – inherited from Error

Type:

proto.fields.Field

message

Field of type STRING – inherited from Error

Type:

proto.fields.Field

stack

Field of type STRING – inherited from Error

Type:

proto.fields.Field

classmethod rule() → MessageRule

Fallback rule to convert between ubii.proto.Error and this type

property args

Tuple of (title, message, stack)

title: str

message: str

stack: str

exception ubii.framework.errors.SessionRuntimeStopServiceError(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: UbiiError

Raise if a service request to stop a ubii.proto.Session is unsuccessful.

title

Field of type STRING – inherited from Error – inherited from UbiiError

Type:

proto.fields.Field

message

Field of type STRING – inherited from Error – inherited from UbiiError

Type:

proto.fields.Field

stack

Field of type STRING – inherited from Error – inherited from UbiiError

Type:

proto.fields.Field

title: str

message: str

stack: str

class ubii.framework.errors.ErrorRule(descriptor: type, wrapper: type)

Bases: MessageRule

Custom MessageRule to convert Error protobuf messages to UbiiError or SessionRuntimeStopServiceError exceptions.

to_python(value, *, absent: bool | None = None)

If the ubii.proto.Error.title starts with 'SessionRuntimeStopService' the message is converted to a SessionRuntimeStopServiceError, otherwise a normal UbiiError is created.

to_proto(value)

Converts back to a protobuf message using the MessageRule implementation from the proto-plus package