DIRAC 9.0.0a64__py3-none-any.whl → 9.0.0a67__py3-none-any.whl

DIRAC/Core/Utilities/ReturnValues.py

@@ -1,255 +1,10 @@
-"""
-   DIRAC return dictionary
+"""Backward compatibility wrapper - moved to DIRACCommon
 
-   Message values are converted to string
+This module has been moved to DIRACCommon.Core.Utilities.ReturnValues to avoid
+circular dependencies and allow DiracX to use these utilities without
+triggering DIRAC's global state initialization.
 
-   keys are converted to string
+All exports are maintained for backward compatibility.
 """
-from __future__ import annotations
-
-import functools
-import sys
-import traceback
-from types import TracebackType
-from typing import Any, Callable, cast, Generic, Literal, overload, Type, TypeVar, Union
-from typing_extensions import TypedDict, ParamSpec, NotRequired
-
-from DIRAC.Core.Utilities.DErrno import strerror
-
-
-T = TypeVar("T")
-P = ParamSpec("P")
-
-
-class DOKReturnType(TypedDict, Generic[T]):
-    """used for typing the DIRAC return structure"""
-
-    OK: Literal[True]
-    Value: T
-
-
-class DErrorReturnType(TypedDict):
-    """used for typing the DIRAC return structure"""
-
-    OK: Literal[False]
-    Message: str
-    Errno: int
-    ExecInfo: NotRequired[tuple[type[BaseException], BaseException, TracebackType]]
-    CallStack: NotRequired[list[str]]
-
-
-DReturnType = Union[DOKReturnType[T], DErrorReturnType]
-
-
-def S_ERROR(*args: Any, **kwargs: Any) -> DErrorReturnType:
-    """return value on error condition
-
-    Arguments are either Errno and ErrorMessage or just ErrorMessage fro backward compatibility
-
-    :param int errno: Error number
-    :param string message: Error message
-    :param list callStack: Manually override the CallStack attribute better performance
-    """
-    callStack = kwargs.pop("callStack", None)
-
-    result: DErrorReturnType = {"OK": False, "Errno": 0, "Message": ""}
-
-    message = ""
-    if args:
-        if isinstance(args[0], int):
-            result["Errno"] = args[0]
-            if len(args) > 1:
-                message = args[1]
-        else:
-            message = args[0]
-
-    if result["Errno"]:
-        message = f"{strerror(result['Errno'])} ( {result['Errno']} : {message})"
-    result["Message"] = message
-
-    if callStack is None:
-        try:
-            callStack = traceback.format_stack()
-            callStack.pop()
-        except Exception:
-            callStack = []
-
-    result["CallStack"] = callStack
-
-    return result
-
-
-# mypy doesn't understand default parameter values with generics so use overloads (python/mypy#3737)
-@overload
-def S_OK() -> DOKReturnType[None]:
-    ...
-
-
-@overload
-def S_OK(value: T) -> DOKReturnType[T]:
-    ...
-
-
-def S_OK(value=None):  # type: ignore
-    """return value on success
-
-    :param value: value of the 'Value'
-    :return: dictionary { 'OK' : True, 'Value' : value }
-    """
-    return {"OK": True, "Value": value}
-
-
-def isReturnStructure(unk: Any) -> bool:
-    """Check if value is an `S_OK`/`S_ERROR` object"""
-    if not isinstance(unk, dict):
-        return False
-    if "OK" not in unk:
-        return False
-    if unk["OK"]:
-        return "Value" in unk
-    else:
-        return "Message" in unk
-
-
-def isSError(value: Any) -> bool:
-    """Check if value is an `S_ERROR` object"""
-    if not isinstance(value, dict):
-        return False
-    if "OK" not in value:
-        return False
-    return "Message" in value
-
-
-def reprReturnErrorStructure(struct: DErrorReturnType, full: bool = False) -> str:
-    errorNumber = struct.get("Errno", 0)
-    message = struct.get("Message", "")
-    if errorNumber:
-        reprStr = f"{strerror(errorNumber)} ( {errorNumber} : {message})"
-    else:
-        reprStr = message
-
-    if full:
-        callStack = struct.get("CallStack")
-        if callStack:
-            reprStr += "\n" + "".join(callStack)
-
-    return reprStr
-
-
-def returnSingleResult(dictRes: DReturnType[Any]) -> DReturnType[Any]:
-    """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.
-
-    :param 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}
-    """
-    # if S_ERROR was returned, we return it as well
-    if not dictRes["OK"]:
-        return dictRes
-    # if there is a Failed, we return the first one in an S_ERROR
-    if "Failed" in dictRes["Value"] and len(dictRes["Value"]["Failed"]):
-        errorMessage = list(dictRes["Value"]["Failed"].values())[0]
-        if isinstance(errorMessage, dict):
-            if isReturnStructure(errorMessage):
-                return cast(DErrorReturnType, errorMessage)
-            else:
-                return S_ERROR(str(errorMessage))
-        return S_ERROR(errorMessage)
-    # if there is a Successful, we return the first one in an S_OK
-    elif "Successful" in dictRes["Value"] and len(dictRes["Value"]["Successful"]):
-        return S_OK(list(dictRes["Value"]["Successful"].values())[0])
-    else:
-        return S_ERROR("returnSingleResult: Failed and Successful dictionaries are empty")
-
-
-class SErrorException(Exception):
-    """Exception class for use with `convertToReturnValue`"""
-
-    def __init__(self, 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)`.
-
-        :param result: The error to propagate
-        :param errCode: the error code to propagate
-        """
-        if not isSError(result):
-            result = S_ERROR(errCode, result)
-        self.result = cast(DErrorReturnType, result)
-
-
-def returnValueOrRaise(result: DReturnType[T], *, 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
-    :exc:`SErrorException` if `result` is an error. This can then by propagated
-    automatically as an `S_ERROR` by wrapping public facing functions with
-    `@convertToReturnValue`.
-
-    :param 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 :exc:`SErrorException` is raised.
-    """
-    if not result["OK"]:
-        if "ExecInfo" in result:
-            raise result["ExecInfo"][0]
-        else:
-            raise SErrorException(result, errorCode)
-    return result["Value"]
-
-
-def convertToReturnValue(func: Callable[P, T]) -> Callable[P, DReturnType[T]]:
-    """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 :exc:`SErrorException`, return the associated `S_ERROR`
-    If `func` raises any other exception type, convert it to an `S_ERROR` object
-
-    :param result: The bare result of a function call
-    :returns: `S_OK`/`S_ERROR`
-    """
-
-    @functools.wraps(func)
-    def wrapped(*args: P.args, **kwargs: P.kwargs) -> DReturnType[T]:
-        try:
-            value = func(*args, **kwargs)
-        except SErrorException as e:
-            return e.result
-        except Exception as e:
-            retval = S_ERROR(f"{repr(e)}: {e}")
-            # Replace CallStack with the one from the exception
-            # Use cast as mypy doesn't understand that sys.exc_info can't return None in an exception block
-            retval["ExecInfo"] = cast(tuple[type[BaseException], BaseException, TracebackType], sys.exc_info())
-            exc_type, exc_value, exc_tb = retval["ExecInfo"]
-            retval["CallStack"] = traceback.format_tb(exc_tb)
-            return retval
-        else:
-            return S_OK(value)
-
-    # functools will copy the annotations. Since we change the return type
-    # we have to update it
-    wrapped.__annotations__["return"] = DReturnType
-    return wrapped
+# Re-export everything from DIRACCommon for backward compatibility
+from DIRACCommon.Core.Utilities.ReturnValues import *  # noqa: F401, F403

DIRAC/Core/Utilities/StateMachine.py

@@ -1,185 +1,19 @@
-""" StateMachine
+"""Backward compatibility wrapper - moved to DIRACCommon
 
-  This module contains the basic blocks to build a state machine (State and StateMachine)
-"""
-from DIRAC import S_OK, S_ERROR, gLogger
-
-
-class State:
-    """
-    State class that represents a single step on a StateMachine, with all the
-    possible transitions, the default transition and an ordering level.
-
-
-    examples:
-      >>> s0 = State(100)
-      >>> s1 = State(0, ['StateName1', 'StateName2'], defState='StateName1')
-      >>> s2 = State(0, ['StateName1', 'StateName2'])
-      # this example is tricky. The transition rule says that will go to
-      # nextState, e.g. 'StateNext'. But, it is not on the stateMap, and there
-      # is no default defined, so it will end up going to StateNext anyway. You
-      # must be careful while defining states and their stateMaps and defaults.
-    """
-
-    def __init__(self, level, stateMap=None, defState=None):
-        """
-        :param int level: each state is mapped to an integer, which is used to sort the states according to that integer.
-        :param list stateMap: it is a list (of strings) with the reachable states from this particular status.
-                              If not defined, we assume there are no restrictions.
-        :param str defState: default state used in case the next state is not in stateMap (not defined or simply not there).
-        """
-
-        self.level = level
-        self.stateMap = stateMap if stateMap else []
-        self.default = defState
-
-    def transitionRule(self, nextState):
-        """
-        Method that selects next state, knowing the default and the transitions
-        map, and the proposed next state. If <nextState> is in stateMap, goes there.
-        If not, then goes to <self.default> if any. Otherwise, goes to <nextState>
-        anyway.
-
-        examples:
-          >>> s0.transitionRule('nextState')
-              'nextState'
-          >>> s1.transitionRule('StateName2')
-              'StateName2'
-          >>> s1.transitionRule('StateNameNotInMap')
-              'StateName1'
-          >>> s2.transitionRule('StateNameNotInMap')
-              'StateNameNotInMap'
-
-        :param str nextState: name of the state in the stateMap
-        :return: state name
-        :rtype: str
-        """
-
-        # If next state is on the list of next states, go ahead.
-        if nextState in self.stateMap:
-            return nextState
-
-        # If not, calculate defaultState:
-        # if there is a default, that one
-        # otherwise is nextState (states with empty list have no movement restrictions)
-        defaultNext = self.default if self.default else nextState
-        return defaultNext
-
-
-class StateMachine:
-    """
-    StateMachine class that represents the whole state machine with all transitions.
-
-    examples:
-      >>> sm0 = StateMachine()
-      >>> sm1 = StateMachine(state = 'Active')
-
-    :param state: current state of the StateMachine, could be None if we do not use the
-        StateMachine to calculate transitions. Beware, it is not checked if the
-        state is on the states map !
-    :type state: None or str
-
-    """
+This module has been moved to DIRACCommon.Core.Utilities.StateMachine to avoid
+circular dependencies and allow DiracX to use these utilities without
+triggering DIRAC's global state initialization.
 
-    def __init__(self, state=None):
-        """
-        Constructor.
-        """
-
-        self.state = state
-        # To be overwritten by child classes, unless you like Nirvana state that much.
-        self.states = {"Nirvana": State(100)}
-
-    def getLevelOfState(self, state):
-        """
-        Given a state name, it returns its level (integer), which defines the hierarchy.
+All exports are maintained for backward compatibility.
+"""
+# Re-export everything from DIRACCommon for backward compatibility
+from DIRACCommon.Core.Utilities.StateMachine import *  # noqa: F401, F403
 
-        >>> sm0.getLevelOfState('Nirvana')
-            100
-        >>> sm0.getLevelOfState('AnotherState')
-            -1
+from DIRAC import gLogger
 
-        :param str state: name of the state, it should be on <self.states> key set
-        :return: `int` || -1 (if not in <self.states>)
-        """
 
-        if state not in self.states:
-            return -1
-        return self.states[state].level
+class StateMachine(StateMachine):  # noqa: F405 pylint: disable=function-redefined
+    """Backward compatibility wrapper - moved to DIRACCommon"""
 
     def setState(self, candidateState, noWarn=False):
-        """Makes sure the state is either None or known to the machine, and that it is a valid state to move into.
-            Final states are also checked.
-
-        examples:
-          >>> sm0.setState(None)['OK']
-              True
-          >>> sm0.setState('Nirvana')['OK']
-              True
-          >>> sm0.setState('AnotherState')['OK']
-              False
-
-        :param state: state which will be set as current state of the StateMachine
-        :type state: None or str
-        :return: S_OK || S_ERROR
-        """
-        if candidateState == self.state:
-            return S_OK(candidateState)
-
-        if not candidateState:
-            self.state = candidateState
-        elif candidateState in self.states:
-            if not self.states[self.state].stateMap:
-                if not noWarn:
-                    gLogger.warn("Final state, won't move", f"({self.state}, asked to move to {candidateState})")
-                return S_OK(self.state)
-            if candidateState not in self.states[self.state].stateMap:
-                gLogger.warn(f"Can't move from {self.state} to {candidateState}, choosing a good one")
-            result = self.getNextState(candidateState)
-            if not result["OK"]:
-                return result
-            self.state = result["Value"]
-            # If the StateMachine does not accept the candidate, return error message
-        else:
-            return S_ERROR(f"setState: {candidateState!r} is not a valid state")
-
-        return S_OK(self.state)
-
-    def getStates(self):
-        """
-        Returns all possible states in the state map
-
-        examples:
-          >>> sm0.getStates()
-              [ 'Nirvana' ]
-
-        :return: list(stateNames)
-        """
-
-        return list(self.states)
-
-    def getNextState(self, candidateState):
-        """
-        Method that gets the next state, given the proposed transition to candidateState.
-        If candidateState is not on the state map <self.states>, it is rejected. If it is
-        not the case, we have two options: if <self.state> is None, then the next state
-        will be <candidateState>. Otherwise, the current state is using its own
-        transition rule to decide.
-
-        examples:
-          >>> sm0.getNextState(None)
-              S_OK(None)
-          >>> sm0.getNextState('NextState')
-              S_OK('NextState')
-
-        :param str candidateState: name of the next state
-        :return: S_OK(nextState) || S_ERROR
-        """
-        if candidateState not in self.states:
-            return S_ERROR(f"getNextState: {candidateState!r} is not a valid state")
-
-        # FIXME: do we need this anymore ?
-        if self.state is None:
-            return S_OK(candidateState)
-
-        return S_OK(self.states[self.state].transitionRule(candidateState))
+        return super().setState(candidateState, noWarn, logger_warn=gLogger.warn)