Usage API

The Usage API provides an interface-agnostic way for QIIME 2 plugin developers to define examples of how to use their plugin’s actions. This enables the programmatic generation of examples for all QIIME 2 interfaces, eliminating the need to maintain specific examples for multiple interfaces.


class qiime2.sdk.usage.Usage

Usage is the base class for Usage driver implementations and should be customized for the interface or implementation.

action(action: qiime2.sdk.usage.UsageAction, inputs: qiime2.sdk.usage.UsageInputs, outputs: qiime2.sdk.usage.UsageOutputNames) → None

This method is a proxy for invoking a QIIME 2 Action. Whether or not the Action is actually invoked is dependent on the driver executing the example.

Parameters
  • action (UsageAction) – Specifies the Plugin and Action for a Usage example.

  • inputs (UsageInputs) – Specifies the inputs to an Action for a Usage example.

  • outputs (UsageOutputNames) – Species the outputs of an Action for a Usage example.

Examples

qiime2.core.testing.examples : Usage examples

get_metadata_column(column_name: str, record: qiime2.sdk.usage.ScopeRecord) → qiime2.sdk.usage.ScopeRecord

Get a Metadata column from previously initialized example Metadata.

Parameters
  • column_name (str) – The name of a column in example Metadata.

  • record (ScopeRecord) – The record associated with example Metadata.

Returns

record – A new scope record for example Metadata column column_name.

Return type

ScopeRecord

get_result(ref: str) → qiime2.sdk.usage.ScopeRecord

Get the record for a Usage example output. This is a convenience method used to access records generated after running Usage.action.

Parameters

ref (str) – Output identifier.

Raises
  • KeyError – If ref is not associated with a record generated by Usage.action.

  • TypeError – If the source type is not an Action.

init_data(ref: str, factory: Callable[sdk.Artifact]) → qiime2.sdk.usage.ScopeRecord

Initialize example Artifact data from a factory. Whether or not the example data is actually created is dependent on the driver executing the example.

Parameters
  • ref (str) – Unique identifier for example data.

  • factory (callable) – A factory that returns an example Artifact.

Returns

record – A record with information about example data.

Return type

ScopeRecord

init_data_collection(ref: str, collection_type: Union[list, set], *records: qiime2.sdk.usage.ScopeRecord) → qiime2.sdk.usage.ScopeRecord

Initialize a collection of data for a Usage example.

Parameters
  • ref (str) – Unique identifier for example data collection.

  • collection_type (list or set) – The type of collection required by an action.

  • records (ScopeRecords belonging to the collection) – The records associated with data to be initialized in the collection.

Returns

record – A record with information about an example of collection data.

Return type

ScopeRecord

init_metadata(ref: str, factory: Callable[metadata.Metadata]) → qiime2.sdk.usage.ScopeRecord

Initialize Metadata for a Usage example. Whether or not the example metadata is actually created is dependent on the driver executing the example.

Parameters
  • ref (str) – Unique identifier for example metadata.

  • factory (callable) – A factory that returns example Metadata.

Returns

record – A record with information about example Metadata.

Return type

ScopeRecord

merge_metadata(ref: str, *records: List[ScopeRecord]) → qiime2.sdk.usage.ScopeRecord

Merge previously initialized example Metadata.

Parameters
  • ref (str) – Unique identifier for merged Metadata.

  • records (ScopeRecords) – Records for the example Metadata to be merged.

Returns

record – A new record with information about the merged example Metadata.

Return type

ScopeRecord