BUG: broken example in documentation (halo plotting)

[neutrinoceros]

Running the example here
https://yt-astro-analysis.readthedocs.io/en/yt_astro_analysis-1.1.0/cookbook/cosmological_analysis.html#plotting-halos

I get

ImportError: No module named yt.extensions.astro_analysis.halo_analysis.halo_catalog.HaloCatalog

This is easily solved with the following patch

diff --git a/yt_astro_analysis/halo_analysis/halo_catalog/__init__.py b/yt_astro_analysis/halo_analysis/halo_catalog/__init__.py
index e69de29..2fac735 100644
--- a/yt_astro_analysis/halo_analysis/halo_catalog/__init__.py
+++ b/yt_astro_analysis/halo_analysis/halo_catalog/__init__.py
@@ -0,0 +1 @@
+from .halo_catalog import HaloCatalog

bug then, the example script still fails with a more exotic error

╭─────────────────────────────── Traceback (most recent call last) ────────────────────────────────╮
│                                                                                                  │
│ /Users/robcleme/dev/yt-project/yt_astro_analysis/t_halo.py:18 in <module>                        │
│                                                                                                  │
│   15 # Create a projection with the halos overplot on top                                        │
│   16 p = yt.ProjectionPlot(ds, "x", "density")                                                   │
│   17 p.annotate_halos(hc)                                                                        │
│ ❱ 18 p.save("/tmp/halo.png")                                                                     │
│   19                                                                                             │
│ /Users/robcleme/.pyenv/versions/3.10.0/envs/yt-astro_dev/lib/python3.10/site-packages/yt/visuali │
│ zation/plot_container.py:106 in newfunc                                                          │
│                                                                                                  │
│    103 │   │   if not args[0]._plot_valid:                                                       │
│    104 │   │   │   # it is the responsibility of _setup_plots to                                 │
│    105 │   │   │   # call args[0].run_callbacks()                                                │
│ ❱  106 │   │   │   args[0]._setup_plots()                                                        │
│    107 │   │   rv = f(*args, **kwargs)                                                           │
│    108 │   │   return rv                                                                         │
│    109                                                                                           │
│                                                                                                  │
│ /Users/robcleme/.pyenv/versions/3.10.0/envs/yt-astro_dev/lib/python3.10/site-packages/yt/visuali │
│ zation/plot_window.py:1233 in _setup_plots                                                       │
│                                                                                                  │
│   1230 │   │   │   │   self.plots[f]._toggle_colorbar(draw_colorbar)                             │
│   1231 │   │                                                                                     │
│   1232 │   │   self._set_font_properties()                                                       │
│ ❱ 1233 │   │   self.run_callbacks()                                                              │
│   1234 │   │   self._plot_valid = True                                                           │
│   1235 │                                                                                         │
│   1236 │   def setup_callbacks(self):                                                            │
│                                                                                                  │
│ /Users/robcleme/.pyenv/versions/3.10.0/envs/yt-astro_dev/lib/python3.10/site-packages/yt/visuali │
│ zation/plot_window.py:1353 in run_callbacks                                                      │
│                                                                                                  │
│   1350 │   │   │   │   │   self._font_color,                                                     │
│   1351 │   │   │   │   )                                                                         │
│   1352 │   │   │   │   CallbackMaker = callback_registry[name]                                   │
│ ❱ 1353 │   │   │   │   callback = CallbackMaker(*args[1:], **kwargs)                             │
│   1354 │   │   │   │   try:                                                                      │
│   1355 │   │   │   │   │   callback(cbw)                                                         │
│   1356 │   │   │   │   except YTDataTypeUnsupported as e:                                        │
│                                                                                                  │
│ /Users/robcleme/dev/yt-project/yt_astro_analysis/yt_astro_analysis/halo_analysis/halo_catalog/pl │
│ ot_modifications.py:140 in __init__                                                              │
│                                                                                                  │
│   137 │   │   │   else:                                                                          │
│   138 │   │   │   │   self.halo_data = halo_catalog.halos_ds.all_data()                          │
│   139 │   │   else:                                                                              │
│ ❱ 140 │   │   │   raise RuntimeError(                                                            │
│   141 │   │   │   │   "halo_catalog argument must be a HaloCatalog object, "                     │
│   142 │   │   │   │   + "a dataset, or a data container."                                        │
│   143 │   │   │   )                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
RuntimeError: halo_catalog argument must be a HaloCatalog object, a dataset, or a data container.

We can patch the error raising statement to get a better idea what's going on

--- a/yt_astro_analysis/halo_analysis/halo_catalog/plot_modifications.py
+++ b/yt_astro_analysis/halo_analysis/halo_catalog/plot_modifications.py
@@ -137,9 +137,10 @@ class HaloCatalogCallback(PlotCallback):
             else:
                 self.halo_data = halo_catalog.halos_ds.all_data()
         else:
-            raise RuntimeError(
+            raise TypeError(
                 "halo_catalog argument must be a HaloCatalog object, "
-                + "a dataset, or a data container."
+                f"a dataset, or a data container. Received {halo_catalog} "
+                f"with type {type(halo_catalog)}"
             )
 
         self.width = width

and we get

TypeError: halo_catalog argument must be a HaloCatalog object, a dataset, or a data container. Received
<yt.extensions.astro_analysis.halo_analysis.halo_catalog.halo_catalog.HaloCatalog object at 0x12059faf0> with type <class
'yt.extensions.astro_analysis.halo_analysis.halo_catalog.halo_catalog.HaloCatalog'>

So what seems to be happening is that by using the extension-style import for yt_astro_analysis classes, we're de facto creating a different namespace than the one used internally, which breaks runtime validation.

The example script works as intended if we use the direct import style instead

-from yt.extensions.astro_analysis.halo_analysis.halo_catalog import HaloCatalog
+from yt_astro_analysis.halo_analysis.halo_catalog import HaloCatalog

A possible solution on the extension side would be to replace if/else validation with try/except.