volatility3.framework.configuration.requirements module

Contains standard Requirement types that all adhere to the RequirementInterface.

These requirement types allow plugins to request simple information types (such as strings, integers, etc) as well as indicating what they expect to be in the context (such as particular layers or symboltables).

class BooleanRequirement(name, description=None, default=None, optional=False)[source]

Bases: SimpleTypeRequirement

A requirement type that contains a boolean value.

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

instance_type

alias of bool

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)

Validates the instance requirement based upon its instance_type.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class BytesRequirement(name, description=None, default=None, optional=False)[source]

Bases: SimpleTypeRequirement

A requirement type that contains a byte string.

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

instance_type

alias of bytes

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)

Validates the instance requirement based upon its instance_type.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class ChoiceRequirement(choices, *args, **kwargs)[source]

Bases: RequirementInterface

Allows one from a choice of strings.

Constructs the object.

Parameters

choices (List[str]) – A list of possible string options that can be chosen from

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Validates the provided value to ensure it is one of the available choices.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class ComplexListRequirement(name, description=None, default=None, optional=False)[source]

Bases: MultiRequirement, ConfigurableRequirementInterface

Allows a variable length list of requirements.

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

build_configuration(context, config_path, _)[source]

Proxies to a ConfigurableInterface if necessary.

Return type

HierarchicalDict

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

abstract construct(context, config_path)[source]

Method for constructing within the context any required elements from subrequirements.

Return type

None

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

classmethod get_requirements()[source]
Return type

List[RequirementInterface]

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

abstract new_requirement(index)[source]

Builds a new requirement based on the specified index.

Return type

RequirementInterface

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Validates the provided value to ensure it is one of the available choices.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class IntRequirement(name, description=None, default=None, optional=False)[source]

Bases: SimpleTypeRequirement

A requirement type that contains a single integer.

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

instance_type

alias of int

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)

Validates the instance requirement based upon its instance_type.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class LayerListRequirement(name, description=None, default=None, optional=False)[source]

Bases: ComplexListRequirement

Allows a variable length list of layers that must exist.

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

build_configuration(context, config_path, _)

Proxies to a ConfigurableInterface if necessary.

Return type

HierarchicalDict

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

construct(context, config_path)[source]

Method for constructing within the context any required elements from subrequirements.

Return type

None

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

classmethod get_requirements()
Return type

List[RequirementInterface]

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

new_requirement(index)[source]

Constructs a new requirement based on the specified index.

Return type

RequirementInterface

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)

Validates the provided value to ensure it is one of the available choices.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class ListRequirement(element_type=<class 'str'>, max_elements=0, min_elements=None, *args, **kwargs)[source]

Bases: RequirementInterface

Allows for a list of a specific type of requirement (all of which must be met for this requirement to be met) to be specified.

This roughly correlates to allowing a number of arguments to follow a command line parameter, such as a list of integers or a list of strings.

It is distinct from a multi-requirement which stores the subrequirements in a dictionary, not a list, and does not allow for a dynamic number of values.

Constructs the object.

Parameters
  • element_type (Type[Union[int, bool, bytes, str]]) – The (requirement) type of each element within the list

  • contain (max_elements; The maximum number of acceptable elements this list can) –

  • min_elements (Optional[int]) – The minimum number of acceptable elements this list can contain

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Check the types on each of the returned values and their number and then call the element type’s check for each one.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class ModuleRequirement(name, description=None, default=False, architectures=None, optional=False)[source]

Bases: ConstructableRequirementInterface, ConfigurableRequirementInterface

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (bool) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

build_configuration(context, _, value)[source]

Builds the appropriate configuration for the specified requirement.

Return type

HierarchicalDict

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

construct(context, config_path)[source]

Constructs the appropriate layer and adds it based on the class parameter.

Return type

None

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

classmethod get_requirements()[source]
Return type

List[RequirementInterface]

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Validate that the value is a valid module

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class MultiRequirement(name, description=None, default=None, optional=False)[source]

Bases: RequirementInterface

Class to hold multiple requirements.

Technically the Interface could handle this, but it’s an interface, so this is a concrete implementation.

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Method to validate the value stored at config_path for the configuration object against a context.

Returns a list containing its own name (or multiple unsatisfied requirement names) when invalid

Parameters
  • context (ContextInterface) – The context object containing the configuration for this requirement

  • config_path (str) – The configuration path for this requirement to test satisfaction

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of configuration-paths to requirements that could not be satisfied

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class PluginRequirement(name, description=None, default=False, optional=False, plugin=None, version=None)[source]

Bases: VersionRequirement

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (bool) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

classmethod matches_required(required, version)
Return type

bool

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)

Method to validate the value stored at config_path for the configuration object against a context.

Returns a list containing its own name (or multiple unsatisfied requirement names) when invalid

Parameters
  • context (ContextInterface) – The context object containing the configuration for this requirement

  • config_path (str) – The configuration path for this requirement to test satisfaction

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of configuration-paths to requirements that could not be satisfied

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class StringRequirement(name, description=None, default=None, optional=False)[source]

Bases: SimpleTypeRequirement

A requirement type that contains a single unicode string.

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

instance_type

alias of str

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)

Validates the instance requirement based upon its instance_type.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class SymbolTableRequirement(*args, **kwargs)[source]

Bases: ConstructableRequirementInterface, ConfigurableRequirementInterface

Class maintaining the limitations on what sort of symbol spaces are acceptable.

Parameters
  • name – The name of the requirement

  • description – A short textual description of the requirement

  • default – The default value for the requirement if no value is provided

  • optional – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

build_configuration(context, _, value)[source]

Builds the appropriate configuration for the specified requirement.

Return type

HierarchicalDict

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

construct(context, config_path)[source]

Constructs the symbol space within the context based on the subrequirements.

Return type

None

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Validate that the value is a valid within the symbol space of the provided context.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class TranslationLayerRequirement(name, description=None, default=None, optional=False, oses=None, architectures=None)[source]

Bases: ConstructableRequirementInterface, ConfigurableRequirementInterface

Class maintaining the limitations on what sort of translation layers are acceptable.

Constructs a Translation Layer Requirement.

The configuration option’s value will be the name of the layer once it exists in the store

Parameters
  • name (str) – Name of the configuration requirement

  • description (Optional[str]) – Description of the configuration requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – A default value (should not be used for TranslationLayers)

  • optional (bool) – Whether the translation layer is required or not

  • oses (Optional[List]) – A list of valid operating systems which can satisfy this requirement

  • architectures (Optional[List]) – A list of valid architectures which can satisfy this requirement

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

build_configuration(context, _, value)[source]

Builds the appropriate configuration for the specified requirement.

Return type

HierarchicalDict

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

construct(context, config_path)[source]

Constructs the appropriate layer and adds it based on the class parameter.

Return type

None

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Validate that the value is a valid layer name and that the layer adheres to the requirements.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class URIRequirement(name, description=None, default=None, optional=False)[source]

Bases: StringRequirement

A requirement type that contains a single unicode string that is a valid URI.

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

instance_type

alias of str

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Always raises a TypeError as instance requirements cannot have children.

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)

Validates the instance requirement based upon its instance_type.

Return type

Dict[str, RequirementInterface]

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement

class VersionRequirement(name, description=None, default=False, optional=False, component=None, version=None)[source]

Bases: RequirementInterface

Parameters
  • name (str) – The name of the requirement

  • description (Optional[str]) – A short textual description of the requirement

  • default (bool) – The default value for the requirement if no value is provided

  • optional (bool) – Whether the requirement must be satisfied or not

add_requirement(requirement)

Adds a child to the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to add as a child-requirement

Return type

None

config_value(context, config_path, default=None)

Returns the value for this Requirement from its config path.

Parameters
  • context (ContextInterface) – the configuration store to find the value for this requirement

  • config_path (str) – the configuration path of the instance of the requirement to be recovered

  • default (Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]) – a default value to provide if the requirement’s configuration value is not found

Return type

Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]], None]

property default: Optional[Union[int, bool, bytes, str, List[Union[int, bool, bytes, str]]]]

Returns the default value if one is set.

property description: str

A short description of what the Requirement is designed to affect or achieve.

classmethod matches_required(required, version)[source]
Return type

bool

property name: str

The name of the Requirement.

Names cannot contain CONFIG_SEPARATOR (‘.’ by default) since this is used within the configuration hierarchy.

property optional: bool

Whether the Requirement is optional or not.

remove_requirement(requirement)

Removes a child from the list of requirements.

Parameters

requirement (RequirementInterface) – The requirement to remove as a child-requirement

Return type

None

property requirements: Dict[str, RequirementInterface]

Returns a dictionary of all the child requirements, indexed by name.

unsatisfied(context, config_path)[source]

Method to validate the value stored at config_path for the configuration object against a context.

Returns a list containing its own name (or multiple unsatisfied requirement names) when invalid

Parameters
  • context (ContextInterface) – The context object containing the configuration for this requirement

  • config_path (str) – The configuration path for this requirement to test satisfaction

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of configuration-paths to requirements that could not be satisfied

unsatisfied_children(context, config_path)

Method that will validate all child requirements.

Parameters
  • context (ContextInterface) – the context containing the configuration data for this requirement

  • config_path (str) – the configuration path of this instance of the requirement

Return type

Dict[str, RequirementInterface]

Returns

A dictionary of full configuration paths for each unsatisfied child-requirement