Decorators

Decorators for DIRAC.

DIRAC.Core.Utilities.Decorators.deprecated(reason, onlyOnce=False)

A decorator to mark a class or function as deprecated.

This will cause a warnings to be generated in the usual log if the item is used (instantiated or called).

If the environment variable DIRAC_DEPRECATED_FAIL is set to a non-empty value, an exception will be raised when the function or class is used.

The decorator can be used before as class or function, giving a reason, for example:

@deprecated("Use functionTwo instead")
def functionOne(...):

If onlyOnce is set to true then the warning will only be generated on the first call or creation of the item. This is useful for things that are likely to get called repeatedly (to prevent generating massive log files); for example:

@deprecated("Use otherClass instead", onlyOnce=True)
class MyOldClass:

If used on a classmethod, it should be used after the @classmethod decorator for example:

@classmethod
@deprecated("Do not put me before @classmethod")
def methodX(cls):
Parameters:
  • reason (str) – Message to display to the user when the deprecated item is used. This should specify what should be used instead.
  • onlyOnce (bool) – If set, the deprecation warning will only be displayed on the first use.
Returns:

A double-function wrapper around the decorated object as required by the python interpreter.

Return type:

function

DIRAC.Core.Utilities.Decorators.executeOnlyIf(attrName, returnedError, attrVal=None)

A decorator to test the value of the attribute of a class before executing a method.

We often have classes in DIRAC that sets an attribute to True when they the object has been successfuly instanciated. And then each and every method test this parameter at the start of it. This is yet another (very) poor man solution to avoid using exceptions.

This decorator will do the test for you.

Pitty, but it breaks the doc, as functools.wrap does not propagate the default attribute discovery

Parameters:
  • attrName – the name of the attribute to test. If undefined, equivalent to its value being None
  • returnedError – what to return if the attribute value is not what we expect
  • attrVal – if set to anything else than None, we check that the attribute value is what is give. If set to None, we just check evaluate __bool__ on the attribute.

For example:

class ExceptionsAreEvil(object):

  _hasBeenInitialized = False

  def __init__(self):
    self._hasBeenInitialized = 'OfCourse'

  @executeOnlyIf("_hasBeenInitialized", S_ERROR("How could I not be initialized ?"))
  def functionOne(...):
    doTheActualWork()

  def stupidMethod(...):

    print "I don't like decorator"
    if not self._hasBeenInitialized:
      return S_ERROR("How could I not be initialized ?")

    finallyDoSomething()