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)

Bases: SimpleTypeRequirement

A requirement type that contains a boolean value.

Parameters:

• name (str) – The name of the requirement

• description (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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

Bases: SimpleTypeRequirement

A requirement type that contains a byte string.

Parameters:

• name (str) – The name of the requirement

• description (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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

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)

Bases: MultiRequirement, ConfigurableRequirementInterface

Allows a variable length list of requirements.

Parameters:

• name (str) – The name of the requirement

• description (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]

abstract construct(context, config_path)

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

Return type:

None

property default: int | bool | bytes | str | List[int | bool | bytes | str] | None

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.

abstract new_requirement(index)

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)

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)

Bases: SimpleTypeRequirement

A requirement type that contains a single integer.

Parameters:

• name (str) – The name of the requirement

• description (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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

Bases: ComplexListRequirement

Allows a variable length list of layers that must exist.

Parameters:

• name (str) – The name of the requirement

• description (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)

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

Return type:

None

property default: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

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)

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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

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)

Bases: ConstructableRequirementInterface, ConfigurableRequirementInterface

Parameters:

• name (str) – The name of the requirement

• description (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)

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)

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

Return type:

None

property default: int | bool | bytes | str | List[int | bool | bytes | str] | None

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.

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)

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)

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 (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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

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)

Bases: VersionRequirement

Parameters:

• name (str) – The name of the requirement

• description (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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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, accumulator=None)

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)

Bases: SimpleTypeRequirement

A requirement type that contains a single unicode string.

Parameters:

• name (str) – The name of the requirement

• description (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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

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)

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)

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

Return type:

None

property default: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

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)

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 (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 (List) – A list of valid operating systems which can satisfy this requirement

• architectures (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)

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)

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

Return type:

None

property default: int | bool | bytes | str | List[int | bool | bytes | str] | None

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)

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)

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 (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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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

classmethod location_from_file(filename)

Returns the URL location from a file parameter (which may be a URL)

Parameters:

filename (str) – The path to the file (either an absolute, relative, or URL path)

Return type:

str

Returns:

The URL for the location of the file

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)

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: int | bool | bytes | str | List[int | bool | bytes | str] | None

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, accumulator=None)

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