Plugin developer API

When developing a QIIME 2 plugin, you will use APIs defined in the qiime2.plugin submodule.

Plugin development API

The Plugin object

Plugin(name, version, website, package=None, project_name=None, citation_text=None, user_support_text=None, short_description=None, description=None, citations=None)

Formats

TextFileFormat(path=None, mode='w')

BinaryFileFormat(path=None, mode='w')

DirectoryFormat(path=None, mode='w')

Action input and output

Sematic types

SemanticType(name, field_names=None, field_members=None, variant_of=None)

Create a new semantic type.

Parameters:

• name (str) – The name of the semantic type: this should match the variable to which the semantic type is assigned.

• field_names (str, iterable of str, optional) – Name(s) of the fields where member types can be placed. This makes the type a composite type, meaning that fields must be provided to produce realized semantic types. These names will define ad-hoc variant types accessible as name.field[field_names member].

• field_members (mapping, optional) – A mapping of strings in field_names to one or more semantic types which are known to be members of the field (the variant type).

• variant_of (VariantField, iterable of VariantField, optional) – Define the semantic type to be a member of one or more variant types allowing it to be placed in the respective fields defined by those variant types.

Returns:

There are several (private) types which may be returned, but anything returned by this factory will cause is_semantic_type to return True.

Return type:

A Semantic Type

Properties()

Primitives and modifiers

Visualization()

Set()

List()

Collection()

Bool()

Int()

Float()

Range()

Start(start, inclusive=True)

End(end, inclusive=False)

Str()

Choices()

Jobs()

Threads()

Metadata

Metadata()

MetadataColumn()

Categorical()

Numeric()

Support functions

TypeMap(mapping)

TypeMatch(listing)

Citations

Citations()

Dictionary that remembers insertion order

CitationRecord(type, fields)

Utility functions

get_available_cores(n_less: int = 0)

Finds the number of currently available (logical) cores. Useful for plugins that need to convert a 0 to a concrete number of cores when 0 is not supported by the underlying/called software.

Parameters:

n_less (int) – The number of cores less than the total number available to request. For example `get_available_cores(n_less=2) with 10 available cores will return 8.

Returns:

The number of cores to be requested.

Return type:

int

Exceptions

ValidationError()

Common base class for all non-exit exceptions.

Plugin testing API

class TestPluginBase(methodName='runTest')

Test harness for simplifying testing QIIME 2 plugins.

TestPluginBase extends unittest.TestCase, with a few extra helpers and assertions.

package

The name of the plugin package to be tested.

Type:

str

test_dir_prefix

The prefix for the temporary testing dir created by the harness.

Type:

str

assertRegisteredSemanticType(semantic_type)

Test assertion for ensuring a plugin’s semantic type is registered.

Fails if the semantic type requested is not found in the Plugin Manager.

Parameters:

semantic_type (A Semantic Type) – The Semantic Type to test the presence of.

assertSemanticTypeRegisteredToFormat(semantic_type, exp_format)

Test assertion for ensuring a semantic type is registered to a

format.

Fails if the semantic type requested is not registered to the format specified with exp_format. Also fails if the semantic type isn’t registered to any format.

Parameters:

• semantic_type (A Semantic Type) – The Semantic Type to check for.

• exp_format (A Format) – The Format to check that the Semantic Type is registed on.

get_data_path(filename)

Convenience method for getting a data asset while testing.

Test data stored in the data/ dir local to the running test can be accessed via this method.

Parameters:

filename (str) – The name of the file to look up.

Returns:

filepath – The materialized filepath to the requested test data.

Return type:

str

get_transformer(from_type, to_type)

Convenience method for getting a registered transformer.

This helper deliberately side-steps the framework’s validation machinery, so that it is possible for plugin developers to test failing conditions.

Parameters:

• from_type (A View Type) – The View type of the source data.

• to_type (A View Type) – The View type to transform to.

Returns:

transformer – The registered tranformer from from_type to to_type.

Return type:

A Transformer Function

setUp()

Test runner setup hook.

If overriding this hook in a test, call __super__ to invoke this method in the overridden hook, otherwise the harness might not work as expected.

tearDown()

Test runner teardown hook.

If overriding this hook in a test, call __super__ to invoke this method in the overridden hook, otherwise the harness might not work as expected.

transform_format(source_format, target, filename=None, filenames=None)

Helper utility for loading data and transforming it.

Combines several other utilities in this class, will load files from data/, as source_format, then transform to the target view.

This helper deliberately side-steps the framework’s validation machinery, so that it is possible for plugin developers to test failing conditions.

Parameters:

• source_format (A Format) – The Format to load the data as.

• target (A View Type) – The View Type to transform the data to.

• filename (str) – The name of the file to load from data. Use this for formats that use a single file in their format definition. Mutually exclusive with the filenames parameter.

• filenames (list[str]) – The names of the files to load from data. Use this for formats that use multiple files in their format definition. Mutually exclusive with the filename parameter.

Returns:

• input (A Format) – The data loaded from data as the specified source_format.

• obs (A View Type) – The loaded data, transformed to the specified target view type.

assert_no_nans_in_tables(fh)

Checks for NaNs present in any of the tables in the indicated file then resets to the head of the file.