ReturnValues

DIRAC return dictionary

Message values are converted to string

keys are converted to string

class DIRAC.Core.Utilities.ReturnValues.DErrorReturnType(_typename, _fields=None, /, **kwargs)

Bases: dict

used for typing the DIRAC return structure

CallStack: typing_extensions.NotRequired[list[str]]
Errno: int
ExecInfo: typing_extensions.NotRequired[tuple[type[BaseException], BaseException, traceback]]
Message: str
OK: Literal[False]
__init__(*args, **kwargs)
clear() None.  Remove all items from D.
copy() a shallow copy of D
fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() a set-like object providing a view on D's items
keys() a set-like object providing a view on D's keys
pop(k[, d]) v, remove specified key and return the corresponding value.

If key is not found, default is returned if given, otherwise KeyError is raised

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() an object providing a view on D's values
class DIRAC.Core.Utilities.ReturnValues.DOKReturnType(_typename, _fields=None, /, **kwargs)

Bases: typing_extensions.TypedDict, Generic[DIRAC.Core.Utilities.ReturnValues.T]

used for typing the DIRAC return structure

OK: Literal[True]
Value: DIRAC.Core.Utilities.ReturnValues.T
__init__(*args, **kwargs)
clear() None.  Remove all items from D.
copy() a shallow copy of D
fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() a set-like object providing a view on D's items
keys() a set-like object providing a view on D's keys
pop(k[, d]) v, remove specified key and return the corresponding value.

If key is not found, default is returned if given, otherwise KeyError is raised

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() an object providing a view on D's values
exception DIRAC.Core.Utilities.ReturnValues.SErrorException(result: DErrorReturnType | str)

Bases: Exception

Exception class for use with convertToReturnValue

__init__(result: DErrorReturnType | str)

Create a new exception return value

If result is a S_ERROR return it directly else convert it to an appropriate value using S_ERROR(result).

Parameters

result – The error to propagate

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

DIRAC.Core.Utilities.ReturnValues.S_ERROR(*args: Any, **kwargs: Any) DIRAC.Core.Utilities.ReturnValues.DErrorReturnType

return value on error condition

Arguments are either Errno and ErrorMessage or just ErrorMessage fro backward compatibility

Parameters
  • errno (int) – Error number

  • message (string) – Error message

  • callStack (list) – Manually override the CallStack attribute better performance

DIRAC.Core.Utilities.ReturnValues.S_OK() DIRAC.Core.Utilities.ReturnValues.DOKReturnType[None]
DIRAC.Core.Utilities.ReturnValues.S_OK(value: DIRAC.Core.Utilities.ReturnValues.T) DIRAC.Core.Utilities.ReturnValues.DOKReturnType[DIRAC.Core.Utilities.ReturnValues.T]

return value on success

Parameters

value – value of the ‘Value’

Returns

dictionary { ‘OK’ : True, ‘Value’ : value }

DIRAC.Core.Utilities.ReturnValues.convertToReturnValue(func: Callable[[DIRAC.Core.Utilities.ReturnValues.P], DIRAC.Core.Utilities.ReturnValues.T]) Callable[[DIRAC.Core.Utilities.ReturnValues.P], Union[DIRAC.Core.Utilities.ReturnValues.DOKReturnType[DIRAC.Core.Utilities.ReturnValues.T], DIRAC.Core.Utilities.ReturnValues.DErrorReturnType]]

Decorate a function to convert return values to S_OK/S_ERROR

If func returns, wrap the return value in S_OK. If func raises SErrorException, return the associated S_ERROR If func raises any other exception type, convert it to an S_ERROR object

Parameters

result – The bare result of a function call

Returns

S_OK/S_ERROR

DIRAC.Core.Utilities.ReturnValues.isReturnStructure(unk: Any) bool

Check if value is an S_OK/S_ERROR object

DIRAC.Core.Utilities.ReturnValues.isSError(value: Any) bool

Check if value is an S_ERROR object

DIRAC.Core.Utilities.ReturnValues.reprReturnErrorStructure(struct: DIRAC.Core.Utilities.ReturnValues.DErrorReturnType, full: bool = False) str
DIRAC.Core.Utilities.ReturnValues.returnSingleResult(dictRes: Union[DIRAC.Core.Utilities.ReturnValues.DOKReturnType[Any], DIRAC.Core.Utilities.ReturnValues.DErrorReturnType]) Union[DIRAC.Core.Utilities.ReturnValues.DOKReturnType[Any], DIRAC.Core.Utilities.ReturnValues.DErrorReturnType]

Transform the S_OK{Successful/Failed} dictionary convention into an S_OK/S_ERROR return. To be used when a single returned entity is expected from a generally bulk call.

Parameters

dictRes – S_ERROR or S_OK( “Failed” : {}, “Successful” : {})

Returns

S_ERROR or S_OK(value)

The following rules are applied:

  • if dictRes is an S_ERROR: returns it as is

  • we start by looking at the Failed directory

  • if there are several items in a dictionary, we return the first one

  • if both dictionaries are empty, we return S_ERROR

  • For an item in Failed, we return S_ERROR

  • Far an item in Successful we return S_OK

Behavior examples (would be perfect unit test :-) ):

{'Message': 'Kaput', 'OK': False} -> {'Message': 'Kaput', 'OK': False}
{'OK': True, 'Value': {'Successful': {}, 'Failed': {'a': 1}}} -> {'Message': '1', 'OK': False}
{'OK': True, 'Value': {'Successful': {'b': 2}, 'Failed': {}}} -> {'OK': True, 'Value': 2}
{'OK': True, 'Value': {'Successful': {'b': 2}, 'Failed': {'a': 1}}} -> {'Message': '1', 'OK': False}
{'OK': True, 'Value': {'Successful': {'b': 2}, 'Failed': {'a': 1, 'c': 3}}} -> {'Message': '1', 'OK': False}
{'OK': True, 'Value': {'Successful': {'b': 2, 'd': 4}, 'Failed': {}}} -> {'OK': True, 'Value': 2}
{'OK': True, 'Value': {'Successful': {}, 'Failed': {}}} ->
    {'Message': 'returnSingleResult: Failed and Successful dictionaries are empty', 'OK': False}
DIRAC.Core.Utilities.ReturnValues.returnValueOrRaise(result: Union[DIRAC.Core.Utilities.ReturnValues.DOKReturnType[DIRAC.Core.Utilities.ReturnValues.T], DIRAC.Core.Utilities.ReturnValues.DErrorReturnType]) DIRAC.Core.Utilities.ReturnValues.T

Unwrap an S_OK/S_ERROR response into a value or Exception

This method assists with using exceptions in DIRAC code by raising SErrorException if result is an error. This can then by propagated automatically as an S_ERROR by wrapping public facing functions with @convertToReturnValue.

Parameters

result – Result of a DIRAC function which returns S_OK/S_ERROR

Returns

The value associated with the S_OK object

Raises

If result[“OK”] is falsey the original exception is re-raised. If no exception is known an SErrorException is raised.