ReturnValues

DIRAC return dictionary

Message values are converted to string

keys are converted to string

class DIRAC.Core.Utilities.ReturnValues.DErrorReturnType

Bases: TypedDict

used for typing the DIRAC return structure

CallStack: list[str]

Errno: int

ExecInfo: tuple[type[BaseException], BaseException, TracebackType]

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 the key is not found, return the default if given; otherwise, raise a KeyError.

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

Bases: TypedDict, Generic[T]

used for typing the DIRAC return structure

OK: Literal[True]

Value: 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 the key is not found, return the default if given; otherwise, raise a KeyError.

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, errCode: int = 0)

Bases: Exception

Exception class for use with convertToReturnValue

__init__(result: DErrorReturnType | str, errCode: int = 0)

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(errCode, result).

Parameters:

result – The error to propagate
errCode – the error code to propagate

add_note(): Exception.add_note(note) – add a note to the exception

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) → 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() → DOKReturnType[None]

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

return value on success

Parameters:: value – value of the ‘Value’
Returns:: dictionary { ‘OK’ : True, ‘Value’ : value }

DIRAC.Core.Utilities.ReturnValues.convertToReturnValue(func: Callable[[P], T]) → Callable[[P], DOKReturnType[T] | 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: DErrorReturnType, full: bool = False) → str

DIRAC.Core.Utilities.ReturnValues.returnSingleResult(dictRes: DOKReturnType[Any] | DErrorReturnType) → DOKReturnType[Any] | 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: DOKReturnType[T] | DErrorReturnType, *, errorCode: int = 0) → 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.