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.
Call
super().method()
and collect the resultsDo something interesting
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
, andqiime2.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.
See also
- 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>'
- 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 areUsageInputs
andUsageOutputNames
.- 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 areUsageAction
andUsageOutputNames
.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 areUsageAction
andUsageInputs
.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.