AnaAlgorithmConfig.py

Go to the documentation of this file.

# Copyright (C) 2002-2020 CERN for the benefit of the ATLAS collaboration
 
# Import(s):
import ROOT
import unittest
import copy
 
class AnaAlgorithmConfig( ROOT.EL.AnaAlgorithmConfig ):
    """Standalone Analysis Algorithm Configuration
 
    This class is used to describe the configuration of an analysis algorithm
    (a C++ class inheriting from EL::AnaAlgorithm) in Python. It behaves
    similar to an Athena configurable, but is implemented in a much simpler
    way.
 
    An example of using it in configuring an EventLoop job could look like:
 
       job = ROOT.EL.Job()
       ...
       from AnaAlgorithm.AnaAlgorithmConfig import AnaAlgorithmConfig
       alg = AnaAlgorithmConfig( "EL::UnitTestAlg2/TestAlg",
                                 property = 1.23 )
       alg.string_property = "Foo"
       job.algsAdd( alg )
 
    Note that the python code doesn't know what properties can actually be set
    on any given C++ algorithm. Any mistake made in the Python configuration
    (apart from syntax errors) is only discovered while initialising the
    analysis job.
    """
 
    # Class/static variable(s):
    printHeaderWidth = 80
    printHeaderPre   = 3
 
    def __init__( self, typeAndName, **kwargs ):
        """Constructor for an algorithm configuration object
 
        Keyword arguments:
          typeAndName -- The type/instance name of the algorithm
 
        Note that you can pass (initial) properties to the constructor like:
 
           alg = AnaAlgorithmConfig( "EL::UnitTestAlg2/TestAlg",
                                     property = 1.23 )
        """
 
        # Call the base class's constructor. Use the default constructor instead
        # of the one receiving the type and name, to avoid ROOT-10872.
        super().__init__()
        self.setTypeAndName( typeAndName )
 
        # Initialise the properties of the algorihm:
        self._props = {}
 
        # Set the properties on the object:
        for key, value in kwargs.items():
            self.setPropertyFromString( key, stringPropValue( value ) )
            self._props[ key ] = copy.deepcopy( value )
 
    def getName( self ):
        """Get the instance name of the algorithm
 
        This is for compatibility with the getName() function of Athena
        configurables.
        """
 
        return self.name()
 
    def getType( self ):
        """Get the type name of the algorithm
 
        This is for compatibility with the getType() function of Athena
        configurables.
        """
 
        return self.type()
 
    def __getattr__( self, name ):
        """Get a previously set property value from the configuration
 
        This function allows us to retrieve the value of a property that was
        already set for the algorithm, to possibly use it in some configuration
        decisions in the Python code itself.
 
        Keyword arguments:
          name -- The name of the property
        """
 
        # Short-circuit internal/dunder attribute lookups, which are never
        # properties (and would otherwise recurse if '_props' is missing):
        if name.startswith( '_' ):
            raise AttributeError( name )
 
        # Fail if the property was not (yet) set:
        if name not in self._props:
            raise AttributeError( f"Property '{name}' was not set on "
                                  f"'{self.type()}/{self.name()}'" )
 
        # Return the property value:
        return self._props[ name ]
 
    def __setattr__( self, key, value ):
        """Set an algorithm property on an existing configuration object
 
        This function allows us to set/override properties on an algorithm
        configuration object. Allowing for the following syntax:
 
           alg = ...
           alg.IntProperty = 66
           alg.FloatProperty = 3.141592
           alg.StringProperty = "Foo"
 
        Keyword arguments:
          key   -- The key/name of the property
          value -- The value to set for the property
        """
 
        # Private variables should be set directly:
        if key[ 0 ] == '_':
            return super().__setattr__( key, value )
 
        # Set the property, and remember its value:
        super().setPropertyFromString( key, stringPropValue( value ) )
        self._props[ key ] = copy.deepcopy( value )
 
    def __eq__( self, other ):
        """Check for equality with another object
 
        The implementation of this is very simple. We only check that the type
        and the name of the algorithms would match.
        """
 
        # First check that the other object is also an AnaAlgorithmConfig one:
        if not isinstance( other, AnaAlgorithmConfig ):
            return False
 
        # Now check whether the type and the name of the algorithms agree:
        return ( ( self.type() == other.type() ) and
                 ( self.name() == other.name() ) )
 
    def __str__( self ):
        """Print the algorithm configuration in a user friendly way
 
        This is just to help with debugging configurations, allowing
        the user to get a nice printout of their job configuration.
        """
 
        if self.isPublicTool():
            name = f'Public Tool {self.type()}/{self.name()}'
        else:
            name = f'Algorithm {self.type()}/{self.name()}'
        result = AnaAlgorithmConfig._printHeader( name )
        result += '\n'
        for key, value in sorted( self._props.items() ):
            if isinstance( value, str ):
                printedValue = f"'{value}'"
            else:
                printedValue = value
            result += f"|- {key}: {indentBy( printedValue, '| ' )}\n"
        result += AnaAlgorithmConfig._printFooter( name )
        return result
 
    def addPrivateTool( self, name, type ):
        """Create a private tool for the algorithm
 
        This function is used in 'standalone' mode to declare a private tool
        for the algorithm, or a private tool for an already declared private
        tool.
 
        Can be used like:
          config.addPrivateTool( 'tool1', 'ToolType1' )
          config.addPrivateTool( 'tool1.tool2', 'ToolType2' )
 
        Keyword arguments:
          name -- The full name of the private tool
          type -- The C++ type of the private tool
        """
 
        # And now set up the Python object that will take care of setting
        # properties on this tool.
 
        # Tokenize the tool's name. In case it is a subtool of a tool, or
        # something possibly even deeper.
        toolNames = name.split( '.' )
 
        # Look up the component that we need to set up the private tool on.
        component = self
        for tname in toolNames[ 0 : -1 ]:
            component = getattr( component, tname )
 
        # Check that the component doesn't have such a (tool) property yet.
        if hasattr( component, toolNames[ -1 ] ):
            raise RuntimeError( f"Tool with name '{name}' already exists" )
 
        # Now set up a smart object as a property on that component.
        component._props[ toolNames[ -1 ] ] = PrivateToolConfig( self, name,
                                                                 type )
 
        # Finally, tell the C++ code what to do.
        self.createPrivateTool( name, type ).ignore()
 
    def addPrivateToolInArray( self, name, type ):
        """Create a private tool in an array for the algorithm
 
        This function is used in 'standalone' mode to declare a
        private tool in a tool array for the algorithm, or a private
        tool in a tool array for an already declared private tool.
 
        Can be used like:
          tool = config.addPrivateToolInArray( 'tool1', 'ToolType1' )
          tool = config.addPrivateToolInArray( 'tool1.tool2', 'ToolType2' )
 
        Keyword arguments:
          name -- The full name of the private tool
          type -- The C++ type of the private tool
        """
 
        # And now set up the Python object that will take care of setting
        # properties on this tool.
 
        # Tokenize the tool's name. In case it is a subtool of a tool, or
        # something possibly even deeper.
        toolNames = name.split( '.' )
 
        # Look up the component that we need to set up the private tool on.
        component = self
        for tname in toolNames[ 0 : -1 ]:
            component = getattr( component, tname )
 
        # Finally, tell the C++ code what to do.
        actualName = self.createPrivateToolInArray( name, type )
 
        # Tokenize the actual tool's name. In case it is a subtool of
        # a tool, or something possibly even deeper.
        actualToolNames = actualName.split( '.' )
 
        # Now set up a smart object as a property on that component.
        config = PrivateToolConfig( self, actualName, type )
        component._props[ actualToolNames[ -1 ] ] = config
        return config
 
    @staticmethod
    def _printHeader( title ):
        """Produce a nice header when printing the configuration
 
        This function is used for printing the header of both algorithms
        and tools.
 
        Keyword arguments:
          indentString -- String used as indentation
          title        -- The title of the algorithm/tool
        """
 
        preLength = AnaAlgorithmConfig.printHeaderPre
        postLength = AnaAlgorithmConfig.printHeaderWidth - 3 - preLength - \
            len( title )
        return f"/{preLength * '*'} {title} {postLength * '*'}"
 
    @staticmethod
    def _printFooter( title ):
        """Produce a nice footer when printing the configuration
 
        This function is used for printing the footer of both algorithms
        and tools.
 
        Keyword arguments:
          indentString -- String used as indentation
          title        -- The title of the algorithm/tool
        """
 
        preLength = AnaAlgorithmConfig.printHeaderPre
        postLength = AnaAlgorithmConfig.printHeaderWidth - 12 - preLength - \
            len( title )
        return f"\\{preLength * '-'} (End of {title}) {postLength * '-'}"
 
 
class PrivateToolConfig:
    """Standalone Private Tool Configuration
 
    This class is used to mimic the behaviour of Athena tool configurable
    classes. To be able to set the properties of private tools used by
    dual-use algorithms in a way that's valid for both Athena and EventLoop.
    """
 
    def __init__( self, algorithm, prefix, type ):
        """Constructor for an private tool configuration object
        """
 
        self._algorithm = algorithm
        self._prefix = prefix
        self._type = type
        self._props = {}
 
    def __getattr__( self, name ):
        """Get a previously set property value from the configuration
 
        This function allows us to retrieve the value of a tool property that
        was already set for an algorithm's private tool, to possibly use it in
        some configuration decisions in the Python code itself.
 
        Keyword arguments:
          name -- The name of the property
        """
 
        # Short-circuit internal/dunder attribute lookups, which are never
        # properties (and would otherwise recurse if '_props' is missing):
        if name.startswith( '_' ):
            raise AttributeError( name )
 
        # Fail if the property was not (yet) set:
        if name not in self._props:
            raise AttributeError(
                f'Property "{name}" was not set on '
                f'"{self._algorithm.type()}/{self._algorithm.name()}.{self._prefix}"' )
 
        # Return the property value:
        return self._props[ name ]
 
    def __setattr__( self, key, value ):
        """Set a tool property on an existing configuration object
 
        This function allows us to set/override properties on a private tool
        of an algorithm configuration object. Allowing for the following syntax:
 
           alg = ...
           alg.Tool.IntProperty = 66
           alg.Tool.FloatProperty = 3.141592
           alg.Tool.StringProperty = "Foo"
 
        Keyword arguments:
          key   -- The key/name of the property
          value -- The value to set for the property
        """
 
        # Private variables should be set directly:
        if key[ 0 ] == '_':
            return super().__setattr__( key, value )
 
        # Construct the full name, used in the C++ code:
        fullName = self._prefix + "." + key
 
        # Set the property, and remember its value:
        self._algorithm.setPropertyFromString( fullName,
                                               stringPropValue( value ) )
        self._props[ key ] = copy.deepcopy( value )
 
    def __str__( self ):
        """Print the private tool configuration in a user friendly way
 
        This is just to help with debugging configurations, allowing
        the user to get a nice printout of their job configuration.
        """
 
        name = f'Private Tool {self._type}/{self._prefix}'
        result = ' \n'
        result += AnaAlgorithmConfig._printHeader( name )
        result += '\n'
        for key, value in sorted( self._props.items() ):
            if isinstance( value, str ):
                printedValue = f"'{value}'"
            else:
                printedValue = value
            result += f"|- {key}: {indentBy( printedValue, '| ' )}\n"
        result += AnaAlgorithmConfig._printFooter( name )
        return result
 
 
def stringPropValue( value ):
    """Helper function producing a string property value"""
 
    stringValue = str( value )
    if isinstance( value, bool ):
        stringValue = str( int( value ) )
    return stringValue
 
 
def indentBy( propValue, indent ):
    """Helper function used in the configuration printout"""
 
    stringValue = str( propValue )
    result = ""
    for stringLine in stringValue.split( '\n' ):
        if len( result ):
            result += "\n" + indent
        result += stringLine
    return result
 
 
#
# Declare some unit tests for the code
#
 

class TestAlgTypeAndName( unittest.TestCase ):
 
    
    def test_singletypename( self ):
        config1 = AnaAlgorithmConfig( "TypeName" )
        self.assertEqual( config1.type(), "TypeName" )
        self.assertEqual( config1.name(), "TypeName" )
        config2 = AnaAlgorithmConfig( "NS::SomeType" )
        self.assertEqual( config2.type(), "NS::SomeType" )
        self.assertEqual( config2.name(), "NS::SomeType" )
 
    
    def test_typeandname( self ):
        config1 = AnaAlgorithmConfig( "TypeName/InstanceName" )
        self.assertEqual( config1.type(), "TypeName" )
        self.assertEqual( config1.name(), "InstanceName" )
        config2 = AnaAlgorithmConfig( "NS::SomeType/Instance" )
        self.assertEqual( config2.type(), "NS::SomeType" )
        self.assertEqual( config2.name(), "Instance" )
 

class TestAlgProperties( unittest.TestCase ):
 
    
    def setUp( self ):
        self.config = AnaAlgorithmConfig( "Type/Name" )
 
    
    def test_propaccess( self ):
        self.config.Prop1 = "Value1"
        self.config.Prop2 = [ "Value2" ]
        self.assertEqual( self.config.Prop1, "Value1" )
        self.assertEqual( self.config.Prop2, [ "Value2" ] )
        self.assertNotEqual( self.config.Prop1, "Foo" )
        self.assertNotEqual( self.config.Prop2, "Value2" )
 
    
    def test_nonexistentprop( self ):
        with self.assertRaises( AttributeError ):
            value = self.config.Prop3
 

class TestAlgPrivateTool( unittest.TestCase ):
 
    
    def setUp( self ):
        self.config = AnaAlgorithmConfig( "AlgType/AlgName" )
 
    
    def test_privatetool( self ):
        self.config.addPrivateTool( "Tool1", "ToolType1" )
        self.config.Tool1.Prop1 = "Value1"
        self.config.Tool1.Prop2 = [ 1, 2, 3 ]
        self.assertEqual( self.config.Tool1.Prop1, "Value1" )
        self.assertEqual( self.config.Tool1.Prop2, [ 1, 2, 3 ] )
 
    
    def test_privatetoolarray( self ):
        tool = self.config.addPrivateToolInArray( "Tool1", "ToolType1" )
        tool.Prop1 = "Value1"
        tool.Prop2 = [ 1, 2, 3 ]
        self.assertEqual( tool.Prop1, "Value1" )
        self.assertEqual( tool.Prop2, [ 1, 2, 3 ] )
 
    
    def test_privatetoolofprivatetool( self ):
        self.config.addPrivateTool( "Tool1", "ToolType1" )
        self.config.addPrivateTool( "Tool1.Tool2", "ToolType2" )
        self.config.Tool1.Tool2.Prop3 = "Foo"
        self.config.Tool1.Tool2.Prop4 = [ "Bar" ]
        self.assertEqual( self.config.Tool1.Tool2.Prop3, "Foo" )
        self.assertEqual( self.config.Tool1.Tool2.Prop4, [ "Bar" ] )
 
    
    def test_nonexistentprop( self ):
        self.config.addPrivateTool( "Tool1", "ToolType1" )
        with self.assertRaises( AttributeError ):
            value = self.config.Tool1.BadProp
        self.config.addPrivateTool( "Tool1.Tool2", "ToolType2" )
        with self.assertRaises( AttributeError ):
            value = self.config.Tool1.Tool2.BadProp
 
    
    def test_nonexistenttool( self ):
        with self.assertRaises( AttributeError ):
            self.config.addPrivateTool( "BadTool.Tool4", "BadToolType" )