From f4da123fd59ecf297776198c86edc84bbdb40f69 Mon Sep 17 00:00:00 2001 From: Macabe Wood Date: Sat, 17 Jan 2026 20:52:18 -0700 Subject: [PATCH 1/7] Adding documentation on RachisWarning and typo in creating and registering transformer --- .../create-register-transformer.md | 2 +- .../how-to-guides/raise-visible-warning.md | 28 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 book/plugins/how-to-guides/raise-visible-warning.md diff --git a/book/plugins/how-to-guides/create-register-transformer.md b/book/plugins/how-to-guides/create-register-transformer.md index 59802ad0..ea167591 100644 --- a/book/plugins/how-to-guides/create-register-transformer.md +++ b/book/plugins/how-to-guides/create-register-transformer.md @@ -4,7 +4,7 @@ Transformers are often short Python functions that convert one file format or data type to another file format or data type. These functions are never directly called by users or developers, so by convention they don't get informative function names (as the annotations of the input and output provide complete detail on what they do). -Here's are two example `transformer` that are [defined and registered in `q2-types`](https://github.com/qiime2/q2-types/blob/e25f9355958755343977e037bbe39110cfb56a63/q2_types/distance_matrix/_transformer.py#L16): +Here are two example `transformer` that are [defined and registered in `q2-types`](https://github.com/qiime2/q2-types/blob/e25f9355958755343977e037bbe39110cfb56a63/q2_types/distance_matrix/_transformer.py#L16): ```python import skbio diff --git a/book/plugins/how-to-guides/raise-visible-warning.md b/book/plugins/how-to-guides/raise-visible-warning.md new file mode 100644 index 00000000..59b7517d --- /dev/null +++ b/book/plugins/how-to-guides/raise-visible-warning.md @@ -0,0 +1,28 @@ +(howto-raise-visible-warning)= +# Raising a Visible Warning + +Warnings raised by the Python `warning` library are suppressed by the QIIME2 framework by defualt. In order to make sure the warnings raised by your plugin are visible on the command line you must use the `RachisWarning` subclass. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. Below is an excerpt from a [QIIME2 plugin registered in `q2-feature-table` importing and raising a `RachisWarning`.](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) + +```python +from qiime2.core.excpetions import RachisWarnings + +def merge_taxa(data: pd.DataFrame) -> pd.DataFrame: + if len(data) > 1: + depths = [] + for taxonomy in data: + max = 0 + for _, row in taxonomy.iterrows(): + depth = row['Taxon'].count(';') + if depth > max: + max = depth + + depths.append(max) + if len(set(depths)) != 1: + warnings.warn( + "You are merging taxonomies with different depths.", + RachisWarning + ) +``` +This plugin has a `RachisWarning` raised when the taxonomies have different depths. Since the `RachisWarning` is a subclass of `UserWarning` from the +built in Python `warnings` library, on which you can find more in depth documentation [here,](https://docs.python.org/3/library/warnings.html) they behave +completely the same outside of command line visibility. \ No newline at end of file From eed8bf0a8bedba0f69eff9f53e8d1bd2197d66a7 Mon Sep 17 00:00:00 2001 From: Macabe Wood Date: Tue, 20 Jan 2026 16:49:39 -0700 Subject: [PATCH 2/7] Small changes --- book/plugins/how-to-guides/raise-visible-warning.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/book/plugins/how-to-guides/raise-visible-warning.md b/book/plugins/how-to-guides/raise-visible-warning.md index 59b7517d..3065b39a 100644 --- a/book/plugins/how-to-guides/raise-visible-warning.md +++ b/book/plugins/how-to-guides/raise-visible-warning.md @@ -1,7 +1,7 @@ (howto-raise-visible-warning)= # Raising a Visible Warning -Warnings raised by the Python `warning` library are suppressed by the QIIME2 framework by defualt. In order to make sure the warnings raised by your plugin are visible on the command line you must use the `RachisWarning` subclass. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. Below is an excerpt from a [QIIME2 plugin registered in `q2-feature-table` importing and raising a `RachisWarning`.](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) +Warnings raised by the Python `warning` library are suppressed by defualt when using . In order to make sure the warnings raised by your plugin are visible in the CLI you must use the `RachisWarning` subclass. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. Below is an [excerpt](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) from from the `q2-feature-table` plugin that raises such a `RachisWarning`. ```python from qiime2.core.excpetions import RachisWarnings @@ -24,5 +24,4 @@ def merge_taxa(data: pd.DataFrame) -> pd.DataFrame: ) ``` This plugin has a `RachisWarning` raised when the taxonomies have different depths. Since the `RachisWarning` is a subclass of `UserWarning` from the -built in Python `warnings` library, on which you can find more in depth documentation [here,](https://docs.python.org/3/library/warnings.html) they behave -completely the same outside of command line visibility. \ No newline at end of file +built in Python `warnings` [library](https://docs.python.org/3/library/warnings.html) they behave completely the same outside of command line visibility. \ No newline at end of file From 8e4ee0de7b3a3c50d9803aee7d05b710a0868e45 Mon Sep 17 00:00:00 2001 From: Macabe Wood Date: Thu, 22 Jan 2026 11:57:46 -0700 Subject: [PATCH 3/7] Small change --- book/plugins/how-to-guides/raise-visible-warning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/plugins/how-to-guides/raise-visible-warning.md b/book/plugins/how-to-guides/raise-visible-warning.md index 3065b39a..1c2bc817 100644 --- a/book/plugins/how-to-guides/raise-visible-warning.md +++ b/book/plugins/how-to-guides/raise-visible-warning.md @@ -1,7 +1,7 @@ (howto-raise-visible-warning)= # Raising a Visible Warning -Warnings raised by the Python `warning` library are suppressed by defualt when using . In order to make sure the warnings raised by your plugin are visible in the CLI you must use the `RachisWarning` subclass. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. Below is an [excerpt](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) from from the `q2-feature-table` plugin that raises such a `RachisWarning`. +Warnings raised by the Python `warning` library are suppressed by defualt when using the command line interface (CLI). In order to make sure the warnings raised by your plugin are visible in the CLI you must use the `RachisWarning` subclass. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. Below is an [excerpt](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) from from the `q2-feature-table` plugin that raises such a `RachisWarning`. ```python from qiime2.core.excpetions import RachisWarnings From 81b4ebf31207dbf5400fe2333fc30136b061d561 Mon Sep 17 00:00:00 2001 From: Macabe Wood Date: Thu, 22 Jan 2026 16:44:32 -0700 Subject: [PATCH 4/7] Finalizing --- book/_toc.yml | 1 + book/plugins/how-to-guides/raise-visible-warning.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index 46f1d704..331133d0 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -45,6 +45,7 @@ parts: - file: plugins/how-to-guides/usage-examples - file: plugins/how-to-guides/format-validation-levels - file: plugins/how-to-guides/handle-exceptions-in-parallel-pipelines + - file: plugins/how-to-guides/raise-visible-warning - file: plugins/explanations/intro sections: - file: plugins/explanations/actions diff --git a/book/plugins/how-to-guides/raise-visible-warning.md b/book/plugins/how-to-guides/raise-visible-warning.md index 1c2bc817..7bb2327a 100644 --- a/book/plugins/how-to-guides/raise-visible-warning.md +++ b/book/plugins/how-to-guides/raise-visible-warning.md @@ -1,5 +1,5 @@ -(howto-raise-visible-warning)= -# Raising a Visible Warning +(howto-= +# Using the RachisWarning Class: An Always-Visible Warning Warnings raised by the Python `warning` library are suppressed by defualt when using the command line interface (CLI). In order to make sure the warnings raised by your plugin are visible in the CLI you must use the `RachisWarning` subclass. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. Below is an [excerpt](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) from from the `q2-feature-table` plugin that raises such a `RachisWarning`. From a80345f0f0f0725f817cde0eac54c5bc6400f2cf Mon Sep 17 00:00:00 2001 From: Macabe Wood Date: Thu, 22 Jan 2026 18:36:28 -0700 Subject: [PATCH 5/7] Small change --- book/plugins/how-to-guides/raise-visible-warning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/plugins/how-to-guides/raise-visible-warning.md b/book/plugins/how-to-guides/raise-visible-warning.md index 7bb2327a..149986c2 100644 --- a/book/plugins/how-to-guides/raise-visible-warning.md +++ b/book/plugins/how-to-guides/raise-visible-warning.md @@ -1,4 +1,4 @@ -(howto-= +(howto-raise-visible-warning)= # Using the RachisWarning Class: An Always-Visible Warning Warnings raised by the Python `warning` library are suppressed by defualt when using the command line interface (CLI). In order to make sure the warnings raised by your plugin are visible in the CLI you must use the `RachisWarning` subclass. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. Below is an [excerpt](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) from from the `q2-feature-table` plugin that raises such a `RachisWarning`. From 80f8aaa709f895f814ce7191222b7bef3736a484 Mon Sep 17 00:00:00 2001 From: Colin Wood Date: Fri, 6 Feb 2026 15:26:29 -0700 Subject: [PATCH 6/7] reformatting --- book/plugins/how-to-guides/raise-visible-warning.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/book/plugins/how-to-guides/raise-visible-warning.md b/book/plugins/how-to-guides/raise-visible-warning.md index 149986c2..00a3a260 100644 --- a/book/plugins/how-to-guides/raise-visible-warning.md +++ b/book/plugins/how-to-guides/raise-visible-warning.md @@ -1,7 +1,11 @@ (howto-raise-visible-warning)= + # Using the RachisWarning Class: An Always-Visible Warning -Warnings raised by the Python `warning` library are suppressed by defualt when using the command line interface (CLI). In order to make sure the warnings raised by your plugin are visible in the CLI you must use the `RachisWarning` subclass. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. Below is an [excerpt](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) from from the `q2-feature-table` plugin that raises such a `RachisWarning`. +Warnings issued by the Python `warning` library are suppressed by defualt when using the command line interface (CLI). +In order to make sure the warnings issued by your plugin are visible in the CLI you must use the `RachisWarning` class. +This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. +Below is an [excerpt](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) from the `q2-feature-table` plugin that may issue such a `RachisWarning`. ```python from qiime2.core.excpetions import RachisWarnings @@ -17,11 +21,13 @@ def merge_taxa(data: pd.DataFrame) -> pd.DataFrame: max = depth depths.append(max) + if len(set(depths)) != 1: warnings.warn( "You are merging taxonomies with different depths.", RachisWarning ) ``` -This plugin has a `RachisWarning` raised when the taxonomies have different depths. Since the `RachisWarning` is a subclass of `UserWarning` from the -built in Python `warnings` [library](https://docs.python.org/3/library/warnings.html) they behave completely the same outside of command line visibility. \ No newline at end of file + +This action issues a `RachisWarning` when the taxonomies have different depths. +Since the `RachisWarning` class is an empty subclass of `UserWarning` from the Python `warnings` [library](https://docs.python.org/3/library/warnings.html), the only difference in behavior is command line visibility. From fda8c549304e5243131a652fb15563f00f1bc03b Mon Sep 17 00:00:00 2001 From: Colin Wood Date: Fri, 6 Feb 2026 15:30:45 -0700 Subject: [PATCH 7/7] small --- book/plugins/how-to-guides/raise-visible-warning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/plugins/how-to-guides/raise-visible-warning.md b/book/plugins/how-to-guides/raise-visible-warning.md index 00a3a260..f2cd9490 100644 --- a/book/plugins/how-to-guides/raise-visible-warning.md +++ b/book/plugins/how-to-guides/raise-visible-warning.md @@ -1,11 +1,11 @@ (howto-raise-visible-warning)= -# Using the RachisWarning Class: An Always-Visible Warning +# Use the RachisWarning Class: An Always-Visible Warning Warnings issued by the Python `warning` library are suppressed by defualt when using the command line interface (CLI). In order to make sure the warnings issued by your plugin are visible in the CLI you must use the `RachisWarning` class. This class can be imported from the QIIME2 framework, specifically from `qiime2.core.exceptions`. -Below is an [excerpt](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) from the `q2-feature-table` plugin that may issue such a `RachisWarning`. +Below is an [excerpt](https://github.com/qiime2/q2-feature-table/blob/b6a312e612338db0f69c97641372e7f0005b43f5/q2_feature_table/_merge.py#L90C12-L93C14) from the `q2-feature-table` plugin that may issue such a warning. ```python from qiime2.core.excpetions import RachisWarnings