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.

Importantly there are two sides to the API, the usage example side, and the interface driver side. A usage example must never call a method which is intended for a usage driver. These methods will be denoted with the following admonition:


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

Interface developers may want to pay special attention to these methods, as they will likely simplify their code.

If the above warning is not present, then the method is likely intended to be used to describe some example and may be used by an example writer, or overriden by a usage driver.

For the docs below, we set the following artificial global, as if we were always in a usage example with a use variable defined. This is only to fool the doctest module. This should never be done in the real world.

>>> import builtins
>>> builtins.use = ExecutionUsage()