capsul.attributes module

capsul.attributes module contains the infrastructure and utility functions needed to define and use a completion system in CAPSUL processes and pipelines.

capsul.attributes.attributes_factory submodule

Attributes factory module

Classes

AttributesFactory

class capsul.attributes.attributes_factory.AttributesFactory(class_types={})

AttributesFactory holds an attributes schema

capsul.attributes.attributes_schema submodule

A schema defines attrinbutes used within a completion framework

Classes

AttributesSchema

EditableAttributes

ProcessAttributes

Functions

set_attribute()

class capsul.attributes.attributes_schema.AttributesSchema

An AttributesSchema has a name, which is used as an identifier to specify completion.

class capsul.attributes.attributes_schema.EditableAttributes(*args, **kwargs)

A set of attributes (group) used to define process parameters attributes. Attributes are traits in the EditableAttributes Controller.

Initilaize the Controller class.

During the class initialization create a class attribute ‘_user_traits’ that contains all the class traits and instance traits defined by user (i.e. the traits that are not automatically defined by HasTraits or Controller). We can access this class parameter with the ‘user_traits’ method.

If user trait parameters are defined directly on derived class, this procedure call the ‘add_trait’ method in order to not share user traits between instances.

class capsul.attributes.attributes_schema.ProcessAttributes(process, schema_dict)

This is the base class for managing attributes for a process.

It stores attributes associated with a Process, for each of its parameters. Attribute values can be accessed “globally” (for the whole process) as ProcessAttributes instance traits. Or each parameter attributes set may be accessed individually, using get_parameters_attributes().

To define attributes for a process, the programmer may subclass ProcessAttributes and define some EditableAttributes in it. Each EditableAttributes is a group of attributes (traits in the EditableAttributes instance or subclass).

A ProcessAttributes subclass should be registered to a factory to be linked to a process name, using the factory_id class variable.

See Capsul advanced usage doc for details.

Initilaize the Controller class.

During the class initialization create a class attribute ‘_user_traits’ that contains all the class traits and instance traits defined by user (i.e. the traits that are not automatically defined by HasTraits or Controller). We can access this class parameter with the ‘user_traits’ method.

If user trait parameters are defined directly on derived class, this procedure call the ‘add_trait’ method in order to not share user traits between instances.

copy(with_values=True)

overloads soma.Controller.copy()

copy_to_single(with_values=True)

Similar to copy(), excepts that it converts list attributes into single values. This is useful within the completion system infrastructure, to get from an attributes set containing lists (process parameters which are lists), a single value allowing to determine a single path.

This method is merely useful to the end user.

get_parameters_attributes()

Get attributes for each process parameter

set_parameter_attributes(parameter, schema, editable_attributes, fixed_attibute_values, allow_list=True)

Set attributes associated with a single process parameter.

Parameters:

• parameter (str) – process parameter name

• schema (str) – schema used for it (input, output, shared)

• editable_attributes (str, EditableAttributes instance, or list of them) – EditableAttributes or id containing attributes traits

• fixed_attibute_values (dict (str/str)) – values of non-editable attributes

• allow_list (bool) – if True (the default), it the process parameter is a list, then attributes are transformed into lists.

capsul.attributes.attributes_schema.set_attribute(object, name, value)

capsul.attributes.completion_engine_factory submodule

Instantiate a default ProcessCompletionEngine

Classes

BuiltinProcessCompletionEngineFactory

class capsul.attributes.completion_engine_factory.BuiltinProcessCompletionEngineFactory

get_completion_engine(process, name=None)

Factory for ProcessCompletionEngine: get an ProcessCompletionEngine instance for a node or process in the context of a given StudyConfig.

The study_config should specify which completion system(s) is (are) used (FOM, …) If nothing is configured, a ProcessCompletionEngine base instance will be returned. It will not be able to perform completion at all, but will conform to the API.

capsul.attributes.completion_engine_iteration submodule

ProcessCompletionEngine dealing with process iterations. This is an internal machinery.

Classes

ProcessCompletionEngineIteration

class capsul.attributes.completion_engine_iteration.ProcessCompletionEngineIteration(process, name=None)

ProcessCompletionEngine specialization for iterative process.

Iterated attributes are given by get_iterated_attributes(). Completion performs a single iteration step, stored in self.capsul_iteration_step

complete_iteration_step(step)

Complete the parameters on the iterated process for a given iteration step.

complete_parameters(process_inputs={}, complete_iterations=True)

Completes file parameters from given inputs parameters, which may include both “regular” process parameters (file names) and attributes.

Parameters:

• process_inputs (dict (optional)) – parameters to be set on the process. It may include “regular” process parameters, and attributes used for completion. Attributes should be in a sub-dictionary under the key “capsul_attributes”.

• complete_iterations (bool (optional)) – if False, iteration nodes inside the pipeline will not run their own completion. Thus parameters for the iterations will not be correctly completed. However this has 2 advantages: 1. it prevents modification of the input pipeline, 2. it will not do iterations completion which will anyway be done (again) when building a workflow in ~capsul.pipeline.pipeline_workflow.workflow_from_pipeline.

get_attribute_values()

Get attributes Controller associated to a process

Returns:

attributes

Return type:

Controller

get_induced_iterative_parameters()

Iterating over some parameters, and triggering completion through attributes, imply that some other parameters will also vary with the iteration. Ex: process A has 2 parameters, “input” and “output”, which are linked by the completion system. If we iterate on A.input, then A.output will also change with the iteration: parameter “output” should thus be included in iterative parameters: it is induced by the iteration over “input”.

This method gives the induced iterative parameters.

get_iterated_attributes()

capsul.attributes.completion_engine submodule

Completion system for Capsul

Classes

ProcessCompletionEngine

SwitchCompletionEngine

PathCompletionEngine

ProcessCompletionEngineFactory

PathCompletionEngineFactory

class capsul.attributes.completion_engine.PathCompletionEngine

Implements building of a single path from a set of attributes for a specific process / parameter

allowed_extensions(process, parameter)

List of possible file extensions associated with a parameter

allowed_formats(process, parameter)

List of possible formats names associated with a parameter

attributes_to_path(process, parameter, attributes)

Build a path from attributes for a given parameter in a process.

This method has to be specialized. The default implementation returns None.

Parameters:

• process (Node or Process instance) –

• parameter (str) –

• attributes (ProcessAttributes instance (Controller)) –

class capsul.attributes.completion_engine.PathCompletionEngineFactory

Get a PathCompletionEngine instance

class capsul.attributes.completion_engine.ProcessCompletionEngine(process, name=None)

Parameters completion from attributes for a process or pipeline node instance, in the context of a specific data organization.

ProcessCompletionEngine can be used directly for a pipeline, which merely delegates completion to its nodes, and has to be subclassed for a data organization framework on a node.

To get a completion engine, use:

completion_engine = ProcessCompletionEngine.get_completion_engine(
    node, name)

Note that this will assign permanently the ProcessCompletionEngine object to its associated node or process. To get and set the attributes set:

attributes = completion_engine.get_attribute_values()
print(attributes.user_traits().keys())
attributes.specific_process_attribute = 'a value'

Once attributes are set, to process with parameters completion:

completion_engine.complete_parameters()

It is possible to have complete_parameters() triggered automatically when attributes or switch nodes change. To set this up, use:

completion_engine.install_auto_completion()

ProcessCompletionEngine can (and should) be specialized, at least to provide the attributes set for a given process. A factory is used to create the correct type of ProcessCompletionEngine for a given process / name: ProcessCompletionEngineFactory

capsul.attributes.fom_completion_engine.FomProcessCompletionEngine is a specialization of ProcessCompletionEngine to manage File Organization Models (FOM).

get_completion_engine()

get_attribute_values()

complete_parameters()

set_parameters()

attributes_to_path()

get_path_completion_engine()

install_auto_completion()

remove_auto_completion()

attributes_changed(obj, name, old, new)

Traits changed callback which triggers parameters update.

This method basically calls complete_parameters() (after some checks).

Users do not normally have to use it directly, it is used internally when install_auto_completion() has been called.

See install_auto_completion()

attributes_to_path(parameter, attributes)

Build a path from attributes for a given parameter in a process.

Parameters:

• parameter (str) –

• attributes (ProcessAttributes instance (Controller)) –

complete_parameters(process_inputs={}, complete_iterations=True)

Completes file parameters from given inputs parameters, which may include both “regular” process parameters (file names) and attributes.

Parameters:

• process_inputs (dict (optional)) – parameters to be set on the process. It may include “regular” process parameters, and attributes used for completion. Attributes should be in a sub-dictionary under the key “capsul_attributes”.

• complete_iterations (bool (optional)) – if False, iteration nodes inside the pipeline will not run their own completion. Thus parameters for the iterations will not be correctly completed. However this has 2 advantages: 1. it prevents modification of the input pipeline, 2. it will not do iterations completion which will anyway be done (again) when building a workflow in ~capsul.pipeline.pipeline_workflow.workflow_from_pipeline.

get_attribute_values()

Get attributes Controller associated to a process or node

Returns:

• attributes (ProcessAttributes instance)

• The default implementation does nothing for a

• single Process instance, and merges attributes from its children if

• the process is a pipeline.

static get_completion_engine(process, name=None)

Get a ProcessCompletionEngine instance for a given process/node within the framework of its StudyConfig factory function.

get_path_completion_engine()

Get a PathCompletionEngine object for the given process. The default implementation queries PathCompletionEngineFactory, but some specific ProcessCompletionEngine implementations may override it for path completion at the process level (FOMs for instance).

install_auto_completion()

Monitor attributes changes and switches changes (which may influence attributes) and recompute parameters completion when needed.

nodes_selection_changed(obj, name, old, new)

Traits changed callback which triggers parameters update.

This method basically calls complete_parameters() (after some checks).

Users do not normally have to use it directly, it is used internally when install_auto_completion() has been called.

See install_auto_completion()

remove_attributes()

Clear attributes controller cache, to allow rebuilding it after a change. This is generally a callback attached to switches changes.

remove_auto_completion()

Remove attributes monitoring and auto-recomputing of parameters.

Reverts install_auto_completion()

remove_switch_observers()

Remove notification callbacks previously set to listen switches state changes.

set_parameters(process_inputs)

Set the given parameters dict to the given process. process_inputs may include regular parameters of the underlying process, and attributes (capsul_attributes: dict).

class capsul.attributes.completion_engine.ProcessCompletionEngineFactory

Get a ProcessCompletionEngine instance

get_completion_engine(process, name=None)

Factory for ProcessCompletionEngine: get an ProcessCompletionEngine instance for a process in the context of a given StudyConfig.

The study_config should specify which completion system(s) is (are) used (FOM, …) If nothing is configured, a ProcessCompletionEngine base instance will be returned. It will not be able to perform completion at all, but will conform to the API.

The base class implementation returns a base ProcessCompletionEngine instance, which is quite incomplete.

class capsul.attributes.completion_engine.SwitchCompletionEngine(process, name=None)

Completion engine specislization for a switch. The switch will propagate attributes from its selected inputs to corresponding outputs, if they can be retrieved from parameters links. Otherwise the countrary will be tried (propagated from outputs to inputs).

get_attribute_values()

Get attributes Controller associated to a process or node

Returns:

• attributes (ProcessAttributes instance)

• The default implementation does nothing for a

• single Process instance, and merges attributes from its children if

• the process is a pipeline.

install_switch_observer(observer=None)

Setup a switch change observation, to remove parameters attributes when the switch state changes.

Parameters:

observer (ProcessCompletionEngine instance) – The observer which should change attributes after switch change. If not specified, the observer is the switch completion engine (self). Notification will call the observer remove_attributes() method.

remove_switch_observer(observer=None)

Remove notification previously set by install_switch_observer()

capsul.attributes.fom_completion_engine submodule

Completion engine for File Organization Models (FOM).

Classes

FomProcessCompletionEngine

FomPathCompletionEngine

FomProcessCompletionEngineIteration

class capsul.attributes.fom_completion_engine.FomPathCompletionEngine

allowed_extensions(process, parameter)

List of possible file extensions associated with a parameter

allowed_formats(process, parameter)

List of possible formats names associated with a parameter

attributes_to_path(process, parameter, attributes)

Build a path from attributes

Parameters:

• process (Process instance) –

• parameter (str) –

• attributes (ProcessAttributes instance (Controller)) –

open_values_attributes(process, parameter)

Attributes with “open” values, not restricted to a list of possible values

class capsul.attributes.fom_completion_engine.FomProcessCompletionEngine(process, name=None)

FOM (File Organization Model) implementation of completion engine.

• A capsul.study_config.StudyConfig also needs to be configured with FOM module, and selected FOMS and directories:

from capsul.api import StudyConfig
from capsul.study_config.config_modules.fom_config import FomConfig
study_config = StudyConfig(modules=StudyConfig.default_modules
                           + ['FomConfig', 'BrainVISAConfig'])
study_config.update_study_configuration('study_config.json')

• Only then a FomProcessCompletionEngine can be created:

process = get_process_instance('morphologist')
fom_completion_engine = FomProcessCompletionEngine(
    process, study_config)

But generally this creation is handled via the ProcessCompletionEngine.get_completion_engine() function:

fom_completion_engine = ProcessCompletionEngine.get_completion_engine(
    process)

Parameters:

name (string (optional)) – name of the process in the FOM dictionary. By default the process.name variable will be used.

create_attributes_with_fom()

create_attributes_with_fom()

To get useful attributes by the fom

get_attribute_values()

Get attributes Controller associated to a process

Returns:

attributes

Return type:

Controller

get_path_completion_engine()

path_attributes(filename, parameter=None)

By the path, find value of attributes

class capsul.attributes.fom_completion_engine.FomProcessCompletionEngineIteration(process, name=None)

get_iterated_attributes()