Debian Codegraph @

tests/plotting/jupyter/test_custom_backends.py

raw
1 """Tests for custom Jupyter backend registration and discovery."""
2
3 from __future__ import annotations
4
5 import contextlib
6 import importlib.util
7 import sys
8 from unittest.mock import MagicMock
9 from unittest.mock import patch
10 import warnings
11
12 import pytest
13
14 import pyvista as pv
15 from pyvista import jupyter as jupyter_mod
16 from pyvista.jupyter import _custom_backend_sources
17 from pyvista.jupyter import _custom_backends
18 from pyvista.jupyter import _get_custom_backend_handler
19 from pyvista.jupyter import _resolve_backend
20 from pyvista.jupyter import _validate_jupyter_backend
21 from pyvista.jupyter import register_jupyter_backend
22 from pyvista.jupyter.notebook import handle_plotter
23
24 has_ipython = bool(importlib.util.find_spec('IPython'))
25 skip_no_ipython = pytest.mark.skipif(not has_ipython, reason='Requires IPython package')
26
27
28 @contextlib.contextmanager
29 def _block_trame_import():
30 """Temporarily make ``from pyvista.trame.jupyter import …`` raise ImportError."""
31 trame_keys = [k for k in sys.modules if k.startswith('pyvista.trame')]
32 saved = {k: sys.modules.pop(k) for k in trame_keys}
33 sentinel = dict.fromkeys(trame_keys) | {'pyvista.trame.jupyter': None}
34 try:
35 with patch.dict(sys.modules, sentinel):
36 yield
37 finally:
38 sys.modules.update(saved)
39
40
41 @pytest.fixture(autouse=True)
42 def _clean_custom_backends():
43 """Remove any custom backends registered during tests."""
44 original = _custom_backends.copy()
45 original_sources = _custom_backend_sources.copy()
46 original_loaded = jupyter_mod._entry_points_loaded
47 yield
48 _custom_backends.clear()
49 _custom_backends.update(original)
50 _custom_backend_sources.clear()
51 _custom_backend_sources.update(original_sources)
52 jupyter_mod._entry_points_loaded = original_loaded
53
54
55 def _mock_handler(plotter, **kwargs):
56 return {'plotter': plotter, **kwargs}
57
58
59 def _replacement_handler(_plotter, **_kwargs):
60 return {'replaced': True}
61
62
63 @skip_no_ipython
64 def test_register_and_validate():
65 register_jupyter_backend('mybackend', _mock_handler)
66 # Should not raise
67 result = _validate_jupyter_backend('mybackend')
68 assert result == 'mybackend'
69
70
71 @skip_no_ipython
72 def test_register_case_insensitive():
73 register_jupyter_backend('MyBackend', _mock_handler)
74 assert _get_custom_backend_handler('mybackend') is _mock_handler
75
76
77 @pytest.mark.parametrize('name', ['static', 'trame', 'server', 'client', 'html', 'none'])
78 def test_register_builtin_collision(name):
79 with pytest.raises(ValueError, match='collides with built-in backend'):
80 register_jupyter_backend(name, _mock_handler)
81
82
83 @skip_no_ipython
84 def test_register_builtin_override_allowed():
85 register_jupyter_backend('static', _mock_handler, override=True)
86 assert _get_custom_backend_handler('static') is _mock_handler
87
88
89 @skip_no_ipython
90 def test_register_custom_collision_warns_and_replaces():
91 register_jupyter_backend('mycollide', _mock_handler)
92 with pytest.warns(UserWarning, match='replaces an existing custom registration'):
93 register_jupyter_backend('mycollide', _replacement_handler)
94 assert _get_custom_backend_handler('mycollide') is _replacement_handler
95
96
97 @skip_no_ipython
98 def test_register_custom_collision_override_silent():
99 register_jupyter_backend('mycollide', _mock_handler)
100 with warnings.catch_warnings():
101 warnings.simplefilter('error')
102 register_jupyter_backend('mycollide', _replacement_handler, override=True)
103 assert _get_custom_backend_handler('mycollide') is _replacement_handler
104
105
106 def test_registered_jupyter_backends_returns_record_with_source():
107 register_jupyter_backend('demo_backend', _mock_handler)
108 records = pv.registered_jupyter_backends()
109 matches = [r for r in records if r.name == 'demo_backend']
110 assert len(matches) == 1
111 record = matches[0]
112 assert record.handler is _mock_handler
113 assert record.source.endswith('_mock_handler')
114
115
116 def test_registered_jupyter_backends_includes_entry_point_source():
117 jupyter_mod._entry_points_loaded = False
118
119 mock_ep = MagicMock()
120 mock_ep.name = 'discovered_backend'
121 mock_ep.value = 'package.module:backend_func'
122 mock_ep.load.return_value = _mock_handler
123
124 with patch('pyvista.jupyter.entry_points', return_value=[mock_ep]):
125 records = pv.registered_jupyter_backends()
126
127 matches = [r for r in records if r.name == 'discovered_backend']
128 assert len(matches) == 1
129 assert matches[0].source == 'package.module:backend_func'
130
131
132 def test_entry_point_load_failure_warns_and_continues():
133 jupyter_mod._entry_points_loaded = False
134
135 broken = MagicMock()
136 broken.name = 'broken_backend'
137 broken.value = 'package:broken'
138 broken.load.side_effect = RuntimeError('broken plugin')
139
140 with (
141 patch('pyvista.jupyter.entry_points', return_value=[broken]),
142 pytest.warns(UserWarning, match='Failed to load pyvista.jupyter_backends entry point'),
143 ):
144 assert _get_custom_backend_handler('broken_backend') is None
145
146
147 def test_entry_point_uses_renamed_group():
148 """Confirm the entry-point group name is ``pyvista.jupyter_backends``."""
149 jupyter_mod._entry_points_loaded = False
150
151 captured: dict[str, object] = {}
152
153 def fake_entry_points(*, group):
154 captured['group'] = group
155 return []
156
157 with patch('pyvista.jupyter.entry_points', side_effect=fake_entry_points):
158 jupyter_mod._ensure_entry_points()
159
160 assert captured['group'] == 'pyvista.jupyter_backends'
161
162
163 @skip_no_ipython
164 def test_get_custom_backend_handler_returns_none_for_unknown():
165 assert _get_custom_backend_handler('nonexistent') is None
166
167
168 @skip_no_ipython
169 def test_validate_lists_custom_backends_in_error():
170 register_jupyter_backend('custom1', _mock_handler)
171 with pytest.raises(ValueError, match='custom1'):
172 _validate_jupyter_backend('totally_invalid')
173
174
175 @skip_no_ipython
176 def test_set_jupyter_backend_custom():
177 register_jupyter_backend('testbackend', _mock_handler)
178 pv.set_jupyter_backend('testbackend')
179 assert pv.global_theme.jupyter_backend == 'testbackend'
180 # Reset
181 pv.set_jupyter_backend(None)
182
183
184 @skip_no_ipython
185 def test_handle_plotter_dispatches_custom():
186 mock_handler = MagicMock(return_value='widget')
187 register_jupyter_backend('mock', mock_handler)
188
189 plotter = MagicMock()
190 result = handle_plotter(plotter, backend='mock', foo='bar')
191
192 mock_handler.assert_called_once_with(plotter, screenshot=None, foo='bar')
193 assert result == 'widget'
194
195
196 @skip_no_ipython
197 def test_entry_point_discovery():
198 import pyvista.jupyter as jupyter_mod
199
200 # Reset discovery state
201 jupyter_mod._entry_points_loaded = False
202
203 mock_ep = MagicMock()
204 mock_ep.name = 'discovered'
205 mock_ep.load.return_value = _mock_handler
206
207 with patch(
208 'pyvista.jupyter.entry_points',
209 return_value=[mock_ep],
210 ):
211 handler = _get_custom_backend_handler('discovered')
212 assert handler is _mock_handler
213
214
215 @skip_no_ipython
216 def test_handle_plotter_falls_back_to_custom_backend_on_trame_import_error():
217 """When trame is unavailable but an entry-point backend is registered, use it."""
218 mock_handler = MagicMock(return_value='ep_widget')
219 register_jupyter_backend('ep_backend', mock_handler)
220
221 plotter = MagicMock()
222
223 with (
224 _block_trame_import(),
225 pytest.warns(UserWarning, match='Using registered backend "ep_backend"'),
226 ):
227 result = handle_plotter(plotter, backend='trame')
228
229 assert result == 'ep_widget'
230 mock_handler.assert_called_once_with(plotter, screenshot=None)
231
232
233 @skip_no_ipython
234 def test_handle_plotter_static_fallback_lists_available_backends():
235 """When trame is unavailable and no custom backends exist, list available backends."""
236 plotter = MagicMock()
237 plotter.last_image = None
238
239 with (
240 _block_trame_import(),
241 patch(
242 'pyvista.jupyter.notebook.show_static_image',
243 return_value='static_img',
244 ) as mock_static,
245 pytest.warns(UserWarning, match='Available backends: "static", "none"'),
246 ):
247 result = handle_plotter(plotter, backend='trame')
248
249 assert result == 'static_img'
250 mock_static.assert_called_once()
251
252
253 @skip_no_ipython
254 def test_resolve_backend_prefers_trame_when_no_custom():
255 """When trame is available and no custom backends registered, returns 'trame'."""
256 assert _resolve_backend() == 'trame'
257
258
259 @skip_no_ipython
260 def test_resolve_backend_prefers_custom_over_trame():
261 """When both trame and a custom backend are available, prefer the custom one."""
262 register_jupyter_backend('mybackend', _mock_handler)
263 assert _resolve_backend() == 'mybackend'
264
265
266 @skip_no_ipython
267 def test_resolve_backend_prefers_custom_over_static():
268 """When trame is unavailable but a custom backend is registered, prefer it."""
269 register_jupyter_backend('mybackend', _mock_handler)
270 with _block_trame_import():
271 assert _resolve_backend() == 'mybackend'
272
273
274 @skip_no_ipython
275 def test_resolve_backend_falls_back_to_static():
276 """When nothing else is available, _resolve_backend returns 'static'."""
277 with _block_trame_import():
278 assert _resolve_backend() == 'static'
279
280
281 @skip_no_ipython
282 def test_handle_plotter_auto_selects_custom_backend():
283 """When backend=None, trame unavailable, registered backend is auto-selected."""
284 mock_handler = MagicMock(return_value='auto_widget')
285 register_jupyter_backend('auto_backend', mock_handler)
286
287 plotter = MagicMock()
288
289 with _block_trame_import():
290 result = handle_plotter(plotter, backend=None)
291
292 assert result == 'auto_widget'
293 mock_handler.assert_called_once_with(plotter, screenshot=None)
294
295
296 @skip_no_ipython
297 def test_handle_plotter_auto_static_warns_install():
298 """When backend=None and only static is available, warn about installing trame."""
299 plotter = MagicMock()
300
301 with (
302 _block_trame_import(),
303 patch(
304 'pyvista.jupyter.notebook.show_static_image',
305 return_value='static_img',
306 ),
307 pytest.warns(UserWarning, match=r'pip install "pyvista\[jupyter\]"'),
308 ):
309 result = handle_plotter(plotter, backend=None)
310
311 assert result == 'static_img'