Inheritance diagram for python.ConfigBlock.ConfigBlock:

Collaboration diagram for python.ConfigBlock.ConfigBlock:

Public Member Functions
def	__init__ (self)

def	setBlockName (self, name)

def	getBlockName (self)

def	factoryName (self)

def	setFactoryName (self, name)

def	instanceName (self)

def	isUsedForConfig (self, config)

def	applyConfigOverrides (self, config)

def	addDependency (self, dependencyName, required=True)

def	hasDependencies (self)

def	getDependencies (self)

def	addOption (self, name, defaultValue, *type, info='', noneAction='ignore', required=False, expertMode=None)

def	setOptionValue (self, name, value)

def	getOptionValue (self, name)

def	getOptions (self)

def	printOptions (self, verbose=False, width=60, indent=" ")

def	hasOption (self, name)

def	__eq__ (self, blockName)

def	__str__ (self)

def	get_instance_count (cls)

def	checkExpertSettings (self, config)

def	__new__ (cls, name, bases, dct)

Static Public Attributes
dictionary	instance_counts = {}

Private Member Functions
def	_is_expert_value (self, rule, value)

Private Attributes
	_blockName

	_factoryName

	_dependencies

	_options

	_expertModeSettings

Detailed Description

the base class for classes implementing individual blocks of
configuration

A configuration block is a sequence of one or more algorithms that
should always be scheduled together, e.g. the muon four momentum
corrections could be a single block, muon selection could then be
another block.  The blocks themselves generally have their own
configuration options/properties specific to the block, and will
perform a dynamic configuration based on those options as well as
the overall job.

The actual configuration of the algorithms in the block will
depend on what other blocks are scheduled before and afterwards,
most importantly some algorithms will introduce shallow copies
that subsequent algorithms will need to run on, and some
algorithms will add selection decorations that subquent algorithms
should use as preselections.

The algorithms get created in a multi-step process (that may be
extended in the future): As a first step each block retrieves
references to the containers it uses (essentially marking its spot
in the processing chain) and also registering any shallow copies
that will be made.  In the second/last step each block then
creates the fully configured algorithms.

One goal is that when the algorithms get created they will have
their final configuration and there needs to be no
meta-configuration data attached to the algorithms, essentially an
inversion of the approach in AnaAlgSequence in which the
algorithms got created first with associated meta-configuration
and then get modified in susequent configuration steps.

For now this is mostly an empty base class, but another goal of
this approach is to make it easier to build another configuration
layer on top of this one, and this class will likely be extended
and get data members at that point.

The child class needs to implement the method `makeAlgs` which is
given a single `ConfigAccumulator` type argument. This is meant to
create the sequence of algorithms that this block configures. This
is currently (28 Jul 2025) called twice and should do the same thing
during both calls, but the plan is to change that to a single call.

The child class should also implement the method `getInstanceName`
which should return a string that is used to distinguish between
multiple instances of the same block. This is used to append the
instance name to the names of all algorithms created by this block,
and may in the future also be used to distinguish between multiple
instances of the block.

Definition at line 92 of file ConfigBlock.py.

Constructor & Destructor Documentation

◆ init()

def python.ConfigBlock.ConfigBlock.__init__ ( self )

Definition at line 147 of file ConfigBlock.py.

     def __init__ (self) :
         self._blockName = ''
         self._factoryName = None
         self._dependencies = []
         self._options = {} # used with block configuration to set arbitrary option
         self._expertModeSettings = {} # dictionary to track expert mode requirements for each option
         self.addOption('groupName', '', type=str,
             info=('Used to specify this block when setting an'
                 ' option at an arbitrary location.'))
         self.addOption('skipOnData', False, type=bool,
             info=('User option to prevent the block from running'
                   ' on data. This only affects blocks that are'
                   ' intended to run on data.'))
         self.addOption('skipOnMC', False, type=bool,
             info=('User option to prevent the block from running'
                   ' on MC. This only affects blocks that are'
                   ' intended to run on MC.'))
         self.addOption('onlyForDSIDs', [], type=list,
             info=('Used to specify which MC DSIDs to allow this'
                   ' block to run on. Each element of the list'
                   ' can be a full DSID (e.g. 410470), or a regex'
                   ' (e.g. 410.* to select all 410xxx DSIDs, or'
                   ' ^(?!410) to veto them). An empty list means no'
                   ' DSID restriction.'))
         self.addOption('propertyOverrides', {}, type=None,
             info=('EXPERT USE ONLY: A dictionary of properties to'
                   ' override at the end of configuration. This should'
                   ' take the form'
                   ' {"algName.toolName.propertyName": value, ...},'
                   ' without any automatically applied postfixes for'
                   ' the algorithm name. THIS IS MEANT TO BE EXPERT'
                   ' USAGE ONLY. Properties that need to be set by'
                   ' the user should be declared as options on the'
                   ' block itself. EXPERT USE ONLY!'),
                   expertMode=True)
         # Increment the instance count for the current class
         cls = type(self)  # Get the actual class of the instance (also derived!)
         if cls not in ConfigBlock.instance_counts:
             ConfigBlock.instance_counts[cls] = 0
         # Note: we do need to check in the call stack that we are
         # in a real makeConfig situation, and not e.g. printAlgs
         stack = inspect.stack()
         for frame_info in stack:
             # Get the class name (if any) from the frame
             parent_cls = frame_info.frame.f_locals.get('self', None)
             if parent_cls is None or not isinstance(parent_cls, ConfigBlock):
                 # If the frame does not belong to an instance of ConfigBlock, it's an external caller
                 if frame_info.function == "makeConfig":
                     ConfigBlock.instance_counts[cls] += 1
                     break
  
  

Member Function Documentation

◆ eq()

def python.ConfigBlock.ConfigBlock.__eq__	(	self,
		blockName
	)

Implementation of == operator. Used for seaching configSeque.
E.g. if blockName in configSeq:

Definition at line 419 of file ConfigBlock.py.

     def __eq__(self, blockName):
         """
         Implementation of == operator. Used for seaching configSeque.
         E.g. if blockName in configSeq:
         """
         return self._blockName == blockName
  
  

◆ new()

def python.ConfigBlock.BlockNameProcessorMeta.__new__	(	cls,
		name,
		bases,
		dct
	)

inherited

Definition at line 53 of file ConfigBlock.py.

     def __new__(cls, name, bases, dct):
         # Automatically apply alphanumeric-only decorator to 'instanceName()' method
         if 'instanceName' in dct and callable(dct['instanceName']):
             dct['instanceName'] = alphanumeric_block_name(dct['instanceName'])
         return super().__new__(cls, name, bases, dct)
  

◆ str()

def python.ConfigBlock.ConfigBlock.__str__ ( self )

Definition at line 427 of file ConfigBlock.py.

     def __str__(self):
         return self._blockName

◆ _is_expert_value()

def python.ConfigBlock.ConfigBlock._is_expert_value	(	self,
		rule,
		value
	)

private

Check whether value matches an expert mode rule.
Rule can be:
- A literal (compared with ==)
- A callable predicate (called with value)
- A special marker string (common callable)

Definition at line 436 of file ConfigBlock.py.

     def _is_expert_value(self, rule, value):
         """
         Check whether value matches an expert mode rule.
         Rule can be:
         - A literal (compared with ==)
         - A callable predicate (called with value)
         - A special marker string (common callable)
         """
         if callable(rule):
             return rule(value)
  
         if isinstance(rule, str):
             if rule == "nonemptystring":
                 return isinstance(value, str) and value != ""
             if rule == "nonemptylist":
                 return isinstance(value, list) and value != []
             if rule == "positiveint":
                 return isinstance(value, int) and value > 0
  
         # Fallback: direct value comparison
         return value == rule
  

◆ addDependency()

def python.ConfigBlock.ConfigBlock.addDependency	(	self,
		dependencyName,
		required = `True`
	)

Add a dependency for the block. Dependency is corresponds to the
blockName of another block. If required is True, will throw an
error if dependency is not present; otherwise will move this
block after the required block. If required is False, will do
nothing if required block is not present; otherwise, it will
move block after required block.

Definition at line 291 of file ConfigBlock.py.

     def addDependency(self, dependencyName, required=True):
         """
         Add a dependency for the block. Dependency is corresponds to the
         blockName of another block. If required is True, will throw an
         error if dependency is not present; otherwise will move this
         block after the required block. If required is False, will do
         nothing if required block is not present; otherwise, it will
         move block after required block.
         """
         if not self.hasDependencies():
             # add option to block ignore dependencies
             self.addOption('ignoreDependencies', [], type=list,
                            info='List of dependencies defined in the ConfigBlock to ignore.')
         self._dependencies.append(ConfigBlockDependency(dependencyName, required))
  

◆ addOption()

def python.ConfigBlock.ConfigBlock.addOption	(		self,
			name,
			defaultValue,
		*	type,
			info = `''`,
			noneAction = `'ignore'`,
			required = `False`,
			expertMode = `None`
	)

declare the given option on the configuration block

This should only be called in the constructor of the
configuration block.

NOTE: The backend to option handling is slated to be replaced
at some point.  This particular function should essentially
stay the same, but some behavior may change.

Definition at line 314 of file ConfigBlock.py.

     def addOption (self, name, defaultValue, *,
                    type, info='', noneAction='ignore', required=False, expertMode=None) :
         """declare the given option on the configuration block
  
         This should only be called in the constructor of the
         configuration block.
  
         NOTE: The backend to option handling is slated to be replaced
         at some point.  This particular function should essentially
         stay the same, but some behavior may change.
         """
         if name in self._options :
             raise KeyError (f'duplicate option: {name}')
         if type not in [str, bool, int, float, list, None] :
             raise TypeError (f'unknown option type: {type}')
         noneActions = ['error', 'set', 'ignore']
         if noneAction not in noneActions :
             raise ValueError (f'invalid noneAction: {noneAction} [allowed values: {noneActions}]')
  
         # Store expert mode settings if provided
         if expertMode is not None:
             if expertMode is True:
                 # in this case we will just check against the default value
                 self._expertModeSettings[name] = True
             elif not isinstance(expertMode, list):
                 raise TypeError (f'expertMode must be a list, got {type(expertMode)}')
             else:
                 # here we will check against a list of custom values
                 self._expertModeSettings[name] = expertMode
  
         setattr (self, name, defaultValue)
         self._options[name] = ConfigBlockOption(type=type, info=info,
             noneAction=noneAction, required=required, default=defaultValue)
  
  

◆ applyConfigOverrides()

def python.ConfigBlock.ConfigBlock.applyConfigOverrides	(	self,
		config
	)

Apply any configuration overrides specified in the block's
`propertyOverrides` option. This is meant to be called at the
end of the configuration process, after all algorithms have been
created and configured.

Definition at line 266 of file ConfigBlock.py.

     def applyConfigOverrides(self, config):
         """
         Apply any configuration overrides specified in the block's
         `propertyOverrides` option. This is meant to be called at the
         end of the configuration process, after all algorithms have been
         created and configured.
         """
         for key, value in self.propertyOverrides.items():
             # Split the key into algorithm name, tool name, and property name
             parts = key.split('.')
             if len(parts) < 2:
                 raise Exception(f"Invalid override key format: {key}")
             alg = config.getAlgorithm(parts[0])
             if alg is None:
                 raise Exception(f"Algorithm {parts[0]} not found in config for override: {key}")
             for name in parts[1:-1]:
                 # Navigate through tools if necessary
                 if hasattr(alg, name):
                     alg = getattr(alg, name)
                 else:
                     raise Exception(f"Tool {name} not found for override: {key}")
             # Set the property on the algorithm/tool. This is probably a
             # horrible hack, but `setattr` didn't work for me.
             alg.__setattr__(parts[-1], value)
  

◆ checkExpertSettings()

def python.ConfigBlock.ConfigBlock.checkExpertSettings	(	self,
		config
	)

Check if any settings require expert mode and validate accordingly.
If any setting is set to a value that requires expert mode but we're
not in expert mode, raise an error.

Definition at line 458 of file ConfigBlock.py.

     def checkExpertSettings(self, config):
         """
         Check if any settings require expert mode and validate accordingly.
         If any setting is set to a value that requires expert mode but we're
         not in expert mode, raise an error.
         """
         for option_name, expert_rule in self._expertModeSettings.items():
             current_value = self.getOptionValue(option_name)
             default_value = self._options[option_name].default
  
             if expert_rule is True:
                 # Any deviation from the default requires expert mode
                 if current_value != default_value:
                     warnings.warn(
                         f"Block '{self.factoryName()}' option '{option_name}' "
                         f"set to '{current_value}' (default '{default_value}'), "
                         f"requires expert mode.",
                         ExpertModeWarning, stacklevel=2
                     )
  
             else:  # it's a list of expert values/markers/predicates
                 for ev in expert_rule:
                     if self._is_expert_value(ev, current_value):
                         warnings.warn(
                             f"Block '{self.factoryName()}' option '{option_name}' "
                             f"set to expert-only value '{current_value}'. "
                             f"Requires expert mode.",
                             ExpertModeWarning, stacklevel=2
                         )
         # All checks passed
         return

◆ factoryName()

def python.ConfigBlock.ConfigBlock.factoryName ( self )

get the factory name for this block

This is mostly to give a reliable means of identifying the type
of block we have in error messages. This is meant to be
automatically set by the factory based on the requested block
name, but there are a number of fallbacks. It is best not to
assume a specific format, this is mostly meant to be used as an
identifier in output messages.

Definition at line 207 of file ConfigBlock.py.

     def factoryName(self):
         """get the factory name for this block
         
         This is mostly to give a reliable means of identifying the type
         of block we have in error messages. This is meant to be
         automatically set by the factory based on the requested block
         name, but there are a number of fallbacks. It is best not to
         assume a specific format, this is mostly meant to be used as an
         identifier in output messages.
         """
         if self._factoryName is not None and self._factoryName != '':
             return self._factoryName
         # If no factory name is set and the block has a name, use that
         if self._blockName is not None and self._blockName != '':
             return self._blockName
         # Use the class name as a fallback
         return self.__class__.__name__
  

◆ get_instance_count()

def python.ConfigBlock.ConfigBlock.get_instance_count ( cls )

Definition at line 432 of file ConfigBlock.py.

     def get_instance_count(cls):
         # Access the current count for this class
         return ConfigBlock.instance_counts.get(cls, 0)
  

◆ getBlockName()

def python.ConfigBlock.ConfigBlock.getBlockName ( self )

Get blockName

Definition at line 203 of file ConfigBlock.py.

     def getBlockName(self):
         """Get blockName"""
         return self._blockName
  

◆ getDependencies()

def python.ConfigBlock.ConfigBlock.getDependencies ( self )

Return the list of dependencies.

Definition at line 310 of file ConfigBlock.py.

     def getDependencies(self):
         """Return the list of dependencies. """
         return self._dependencies
  

◆ getOptions()

def python.ConfigBlock.ConfigBlock.getOptions ( self )

Return a copy of the options associated with the block

Definition at line 382 of file ConfigBlock.py.

     def getOptions(self):
         """Return a copy of the options associated with the block"""
         return self._options.copy()
  
  

◆ getOptionValue()

def python.ConfigBlock.ConfigBlock.getOptionValue	(	self,
		name
	)

Returns config option value, if present; otherwise return None

Definition at line 376 of file ConfigBlock.py.

     def getOptionValue(self, name):
         """Returns config option value, if present; otherwise return None"""
         if name in self._options:
             return getattr(self, name)
  
  

◆ hasDependencies()

def python.ConfigBlock.ConfigBlock.hasDependencies ( self )

Return True if there is a dependency.

Definition at line 306 of file ConfigBlock.py.

     def hasDependencies(self):
         """Return True if there is a dependency."""
         return bool(self._dependencies)
  

◆ hasOption()

def python.ConfigBlock.ConfigBlock.hasOption	(	self,
		name
	)

whether the configuration block has the given option

WARNING: The backend to option handling is slated to be
replaced at some point.  This particular function may change
behavior, interface or be removed/replaced entirely.

Definition at line 409 of file ConfigBlock.py.

     def hasOption (self, name) :
         """whether the configuration block has the given option
  
         WARNING: The backend to option handling is slated to be
         replaced at some point.  This particular function may change
         behavior, interface or be removed/replaced entirely.
         """
         return name in self._options
  
  

◆ instanceName()

def python.ConfigBlock.ConfigBlock.instanceName ( self )

Get the name of the instance

The name of the instance is used to distinguish between multiple
instances of the same block. Most importantly, this will be
appended to the names of all algorithms created by this block.
This defaults to an empty string, but block implementations
should override it with an appropriate name based on identifying
options set on this instance. A typical example would be the
name of the (main) container, plus potentially the selection or
working point.

Ideally all blocks should override this method, but for backward
compatibility (28 Jul 25) it defaults to an empty string.

Definition at line 234 of file ConfigBlock.py.

     def instanceName(self):
         """Get the name of the instance
  
         The name of the instance is used to distinguish between multiple
         instances of the same block. Most importantly, this will be
         appended to the names of all algorithms created by this block.
         This defaults to an empty string, but block implementations
         should override it with an appropriate name based on identifying
         options set on this instance. A typical example would be the
         name of the (main) container, plus potentially the selection or
         working point.
  
         Ideally all blocks should override this method, but for backward
         compatibility (28 Jul 25) it defaults to an empty string.
         """
         return ''
  

◆ isUsedForConfig()

def python.ConfigBlock.ConfigBlock.isUsedForConfig	(	self,
		config
	)

whether this block should be used for the given configuration

This is used by `ConfigSequence` to determine whether this block
should be included in the configuration.

Definition at line 251 of file ConfigBlock.py.

     def isUsedForConfig(self, config):
         """
         whether this block should be used for the given configuration
  
         This is used by `ConfigSequence` to determine whether this block
         should be included in the configuration.
         """
         if self.skipOnData and config.dataType() is DataType.Data:
             return False
         if self.skipOnMC and config.dataType() is not DataType.Data:
             return False
         if not filter_dsids(self.onlyForDSIDs, config):
             return False
         return True
  

◆ printOptions()

def python.ConfigBlock.ConfigBlock.printOptions	(	self,
		verbose = `False`,
		width = `60`,
		indent = `" "`
	)

Prints options and their values

Definition at line 387 of file ConfigBlock.py.

     def printOptions(self, verbose=False, width=60, indent="    "):
         """
         Prints options and their values
         """
         def printWrap(text, width=60, indent="    "):
             wrapper = textwrap.TextWrapper(width=width, initial_indent=indent,
                 subsequent_indent=indent)
             for line in wrapper.wrap(text=text):
                 logCPAlgCfgBlock.info(line)
  
         for opt, vals in self.getOptions().items():
             if verbose:
                 logCPAlgCfgBlock.info(indent + f"\033[4m{opt}\033[0m: {self.getOptionValue(opt)}")
                 logCPAlgCfgBlock.info(indent*2 + f"\033[4mtype\033[0m: {vals.type}")
                 logCPAlgCfgBlock.info(indent*2 + f"\033[4mdefault\033[0m: {vals.default}")
                 logCPAlgCfgBlock.info(indent*2 + f"\033[4mrequired\033[0m: {vals.required}")
                 logCPAlgCfgBlock.info(indent*2 + f"\033[4mnoneAction\033[0m: {vals.noneAction}")
                 printWrap(f"\033[4minfo\033[0m: {vals.info}", indent=indent*2)
             else:
                 logCPAlgCfgBlock.info(indent + f"{ opt}: {self.getOptionValue(opt)}")
  
  

◆ setBlockName()

def python.ConfigBlock.ConfigBlock.setBlockName	(	self,
		name
	)

Set blockName

Definition at line 199 of file ConfigBlock.py.

     def setBlockName(self, name):
         """Set blockName"""
         self._blockName = name
  

◆ setFactoryName()

def python.ConfigBlock.ConfigBlock.setFactoryName	(	self,
		name
	)

set the factory name for this block

This is meant to be called automatically by the factory based on
the requested block name. If you are creating a block without a factory,
you can call this method to set the factory name manually.

Definition at line 225 of file ConfigBlock.py.

     def setFactoryName(self, name):
         """set the factory name for this block
         
         This is meant to be called automatically by the factory based on
         the requested block name. If you are creating a block without a factory,
         you can call this method to set the factory name manually.
         """
         self._factoryName = name
  

◆ setOptionValue()

def python.ConfigBlock.ConfigBlock.setOptionValue	(	self,
		name,
		value
	)

set the given option on the configuration block

NOTE: The backend to option handling is slated to be replaced
at some point.  This particular function should essentially
stay the same, but some behavior may change.

Definition at line 349 of file ConfigBlock.py.

     def setOptionValue (self, name, value) :
         """set the given option on the configuration block
  
         NOTE: The backend to option handling is slated to be replaced
         at some point.  This particular function should essentially
         stay the same, but some behavior may change.
         """
  
         if name not in self._options :
             raise KeyError (f'unknown option "{name}" in block "{self.__class__.__name__}"')
         noneAction = self._options[name].noneAction
         if value is not None or noneAction == 'set' :
             # check type if specified
             optType = self._options[name].type
             # convert int to float to prevent crash
             if optType is float and type(value) is int:
                 value = float(value)
             if optType is not None and optType != type(value):
                 raise ValueError(f'{name} for block {self.__class__.__name__} should '
                     f'be of type {optType} not {type(value)}')
             setattr (self, name, value)
         elif noneAction == 'ignore' :
             pass
         elif noneAction == 'error' :
             raise ValueError (f'passed None for setting option {name} with noneAction=error')
  
  

Member Data Documentation

◆ _blockName

python.ConfigBlock.ConfigBlock._blockName

private

Definition at line 148 of file ConfigBlock.py.

◆ _dependencies

python.ConfigBlock.ConfigBlock._dependencies

private

Definition at line 150 of file ConfigBlock.py.

◆ _expertModeSettings

python.ConfigBlock.ConfigBlock._expertModeSettings

private

Definition at line 152 of file ConfigBlock.py.

◆ _factoryName

python.ConfigBlock.ConfigBlock._factoryName

private

Definition at line 149 of file ConfigBlock.py.

◆ _options

python.ConfigBlock.ConfigBlock._options

private

Definition at line 151 of file ConfigBlock.py.

◆ instance_counts

dictionary python.ConfigBlock.ConfigBlock.instance_counts = {}

static

Definition at line 145 of file ConfigBlock.py.

The documentation for this class was generated from the following file:

ConfigBlock.py

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __eq__()

◆ __new__()

◆ __str__()

◆ _is_expert_value()

◆ addDependency()

◆ addOption()

◆ applyConfigOverrides()

◆ checkExpertSettings()

◆ factoryName()

◆ get_instance_count()

◆ getBlockName()

◆ getDependencies()

◆ getOptions()

◆ getOptionValue()

◆ hasDependencies()

◆ hasOption()

◆ instanceName()

◆ isUsedForConfig()

◆ printOptions()

◆ setBlockName()

◆ setFactoryName()

◆ setOptionValue()

Member Data Documentation

◆ _blockName

◆ _dependencies

◆ _expertModeSettings

◆ _factoryName

◆ _options

◆ instance_counts

◆ init()

◆ eq()

◆ new()

◆ str()