Usage API (for interface drivers)

class qiime2.sdk.usage.Usage(asynchronous: bool = False)

The base implementation of a Usage diver.

Typically a usage driver will override some method. For example, action(), to perform some interesting functionality.

>>> def action(self, action, inputs, outputs):
...    # First a driver should call super, to generate variables
...    variables = super().action(action, inputs, output)
...
...    # then something can be done with them such as:
...    for key, var in variables._asdict().items():
...        self.some_stateful_object[key] = var.execute()
...    # or perhaps the inputs are more interesting:
...    self.other_state.update(
...        inputs.map_variables(lambda x: x.execute()))
...
...    # always remember to return what the super()'ed call returns
...    return variables

This is the typical “sandwich pattern” for overriding the methods which communicate some action to perform.

  1. Call super().method() and collect the results

  2. Do something interesting

  3. Return the results

There are many methods available for a driver implementation to override. For examples of the above pattern, see the source code for the built-in implementations of: DiagnosticUsage, ExecutionUsage, and qiime2.plugins.ArtifactAPIUsage

__init__(asynchronous: bool = False)

Constructor for Usage.

Warning

For use by interface drivers only. Do not use in a written usage example.

asynchronous: bool

Whether the execution should be represented via .asynchronous() calls. This can typically be ignored in subclasses.

Warning

For use by interface drivers only. Do not use in a written usage example.

namespace: Set[str]

A set of names which may collide in a given context. A driver should add strings to this set as is needed; any variables created will have their interface name compared to, and added to this set.

Warning

For use by interface drivers only. Do not use in a written usage example.

usage_variable(name: str, factory: Callable[[], Any], var_type: Literal['artifact', 'artifact_collection', 'visualization', 'visualization_collection', 'metadata', 'column', 'format']) UsageVariable

Initialize a UsageVariable class (called by the base implementation)

Warning

For use by interface drivers only. Do not use in a written usage example.

This should be overriden to specialize the class used by your driver.

Examples

>>> def usage_variable(self, name, factory, var_type):
...     return MyUsageVariable(name, factory, var_type, self,
...                            my_extra_thing='magic')
render(flush: bool = False) Any

Return some rendering of the state up to this point.

Warning

For use by interface drivers only. Do not use in a written usage example.

The default implementation raises NotImplementedError.

Parameters:

flush (bool) – Whether to “flush” (forget) the rendered state after calling, or not. This is useful if the driver is calling render many times.

Returns:

The output is driver specific, but usually a string or list.

Return type:

Any

class qiime2.sdk.usage.UsageVariable(name: str, factory: Callable[[], Any], var_type: Literal['artifact', 'artifact_collection', 'visualization', 'visualization_collection', 'metadata', 'column', 'format'], usage: Usage)

A variable which represents some QIIME 2 generate-able value.

These should not be used to represent primitive values such as strings, numbers, booleans, or lists/sets thereof.

__init__(name: str, factory: Callable[[], Any], var_type: Literal['artifact', 'artifact_collection', 'visualization', 'visualization_collection', 'metadata', 'column', 'format'], usage: Usage)

Constructor for UsageVariable. Generally initialized for you.

Warning

For use by interface drivers only (and rarely at that). Do not use in a written usage example.

Parameters:
  • name (str) – The name of this variable (interfaces will use this as a starting point).

  • factory (Callable[[], Any]) – A function which will return a realized value of var_type.

  • var_type ('artifact', 'artifact_collection', 'visualization',) – ‘visualization_collection’, ‘metadata’, ‘column’, ‘format’ The type of value which will be returned by the factory. Most are self-explanatory, but “format” indicates that the factory produces a QIIME 2 file format or directory format, which is used for importing data.

  • use (Usage) – The currently executing usage driver. Provided for convenience.

name: str

The name of the variable, may differ from to_interface_name().

Warning

For use by interface drivers only. Do not use in a written usage example.

var_type: Literal['artifact', 'artifact_collection', 'visualization', 'visualization_collection', 'metadata', 'column', 'format']

The general type of this variable.

Warning

For use by interface drivers only. Do not use in a written usage example.

value: Any

The value of this variable, or DEFERRED. See is_deferred.

Warning

For use by interface drivers only. Do not use in a written usage example.

factory: Callable[[], Any]

The factory which produces the value. Generally execute() should be used as it will calculate the results once, instead of generating a new object each time.

Warning

For use by interface drivers only (and rarely at that). Do not use in a written usage example.

use: Usage

The current Usage instance being used. Typically this is an instance of a subclass.

Warning

For use by interface drivers only. It won’t break anything, but it would be super-super-super weird to use in a written usage example.

property is_deferred: bool

Check if the value of this variable is available.

Warning

For use by interface drivers only. Do not use in a written usage example.

to_interface_name() str

Convert this variable to an interface-specific name.

Warning

For use by interface drivers only. Do not use in a written usage example.

This method should generally be overriden by a driver to be interface-specific.

Examples

>>> class MyUsageVariable(UsageVariable):
...     def to_interface_name(self):
...         return '<option> ' + self.name.replace('_', '-')
>>> var = MyUsageVariable('foo_bar', lambda: ..., 'artifact', use)
>>> var.to_interface_name()
'<option> foo-bar'
execute() Any

Execute the factory to produce a value, this is stored and returned.

Warning

For use by interface drivers only. Do not use in a written usage example.

Examples

>>> var = UsageVariable('foo', lambda: '<pretend artifact>',
...                     'artifact', use)
>>> var.value
<object object ...>
>>> var.execute()
'<pretend artifact>'
>>> var.value
'<pretend artifact>'

See also

factory, value

save(filepath: str, ext: str | None = None) str

Save the value of this variable to a filepath. The final path is returned.

Warning

For use by interface drivers only. Do not use in a written usage example.

Parameters:
  • filepath (path) – The filepath to save to.

  • ext (str) – The extension to append. May be ‘ext’ or ‘.ext’. If the extension is already present on filepath, it is not added.

Returns:

Path saved to, including the extension if added.

Return type:

path

class qiime2.sdk.usage.UsageAction(plugin_id: str, action_id: str)

An object which represents a deferred lookup for a QIIME 2 action.

One of three “argument objects” used by Usage.action(). The other two are UsageInputs and UsageOutputNames.

plugin_id: str

The (typically under-scored) name of a plugin, e.g. “my_plugin”.

Warning

For use by interface drivers only. Do not use in a written usage example.

action_id: str

The (typically under-scored) name of an action, e.g. “my_action”.

Warning

For use by interface drivers only. Do not use in a written usage example.

get_action() Action

Retrieve the actual SDK object (qiime2.sdk.Action)

Warning

For use by interface drivers only. Do not use in a written usage example.

Returns:

action

Return type:

instance of qiime2.sdk.Action subclass

Raises:

KeyError – If the action parameterized by this object does not exist in the pre-initialized plugin manager.

class qiime2.sdk.usage.UsageInputs(**kwargs)

A dict-like mapping of parameters to arguments for invoking an action.

One of three “argument objects” used by Usage.action(). The other two are UsageAction and UsageOutputNames.

Parameters should match the signature of the associated action, and arguments may be UsageVariable s or primitive values.

map_variables(function)

Convert variables into something else, leaving primitives alone.

Warning

For use by interface drivers only. Do not use in a written usage example.

Parameters:

function (Callable[[UsageVariable], Any]) – The function to map over all variables. This function will not be called on any primitive values.

Returns:

A new dictionary of key-value pairs where all variables have been converted by function.

Return type:

dict

Examples

>>> # Example situation
>>> var = use.usage_variable('foo', lambda: ..., 'artifact')
>>> inputs = UsageInputs(foo=var, bar='bar')
>>> inputs.map_variables(lambda v: v.to_interface_name())
{'foo': 'foo', 'bar': 'bar'}
>>> inputs.map_variables(lambda v: v.execute())
{'foo': ..., 'bar': 'bar'}
__getitem__(key)

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.

__contains__(key)

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.

keys()

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.

values()

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.

items()

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.

class qiime2.sdk.usage.UsageOutputNames(**kwargs)

A dict-like mapping of action outputs to desired names.

One of three “argument objects” used by Usage.action(). The other two are UsageAction and UsageInputs.

All names must be strings.

Note

The order defined by this object will dictate the order of the variables returned by Usage.action().

__getitem__(key)

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.

__contains__(key)

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.

keys()

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.

values()

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.

items()

Same as a dictionary.

Warning

For use by interface drivers only. Do not use in a written usage example.