Debian Codegraph @

pyvista/core/utilities/reader_registry.py

raw
1 """Pluggable reader registry for custom file formats."""
2
3 from __future__ import annotations
4
5 import atexit
6 from importlib.metadata import EntryPoint
7 from importlib.metadata import entry_points
8 import pathlib
9 import shutil
10 import tempfile
11 from typing import TYPE_CHECKING
12 from typing import Any
13 from typing import NamedTuple
14 from typing import Protocol
15 from typing import TypedDict
16 from typing import overload
17
18 import pooch
19
20 from pyvista._warn_external import warn_external
21 from pyvista.core.utilities._registry_helpers import handler_source
22 from pyvista.core.utilities.reader import CLASS_READERS
23
24 if TYPE_CHECKING:
25 from collections.abc import Callable
26
27 from pyvista.core.dataset import DataSet
28
29
30 class ReaderHandler(Protocol):
31 """Callable that reads *path* and returns a :class:`pyvista.DataSet`."""
32
33 def __call__(self, path: str, /, **kwargs: Any) -> DataSet:
34 """Read *path* and return the resulting dataset."""
35
36
37 class ReaderRegistration(NamedTuple):
38 """Describe one registered custom reader.
39
40 Returned by :func:`~pyvista.registered_readers`.
41
42 .. versionadded:: 0.48.0
43
44 Attributes
45 ----------
46 extension : str
47 File extension the reader is registered against, including the
48 leading dot (e.g. ``'.myformat'``).
49 handler : callable
50 The reader callable.
51 source : str
52 Human-readable origin in the form ``'module.qualname'`` for
53 explicit registrations or the entry-point ``value`` for
54 plugin-discovered registrations.
55
56 """
57
58 extension: str
59 handler: ReaderHandler
60 source: str
61
62
63 class _RegistryState(TypedDict):
64 ext: dict[str, ReaderHandler]
65 sources: dict[str, str]
66 pending: dict[str, list[EntryPoint]]
67 entry_points_loaded: bool
68
69
70 class LocalFileRequiredError(Exception):
71 """Raise from a registered reader to signal it needs a local file path.
72
73 When :func:`pyvista.read` passes a remote URI to a custom reader and
74 the reader raises this exception, PyVista will download the file to a
75 temporary local path and retry the reader automatically.
76
77 Examples
78 --------
79 >>> import pyvista as pv
80 >>> from pyvista.core.utilities.reader_registry import LocalFileRequiredError
81 >>> @pv.register_reader('.myformat') # doctest: +SKIP
82 ... def my_reader(path, **kwargs):
83 ... if '://' in path:
84 ... raise LocalFileRequiredError
85 ... ...
86
87 """
88
89
90 _custom_ext_readers: dict[str, ReaderHandler] = {}
91 _custom_ext_reader_sources: dict[str, str] = {}
92 # Entry-point metadata, populated by ``_ensure_entry_points``. Maps each
93 # extension to the list of ``EntryPoint`` records that declared it.
94 # The plugin module itself is *not* imported until that extension is
95 # actually requested via :func:`_get_ext_handler`, keeping
96 # ``pv.read``/``pv.save`` calls for built-in formats free of third-party
97 # plugin import cost.
98 _pending_ext_readers: dict[str, list[EntryPoint]] = {}
99 _entry_points_loaded: bool = False
100 _temp_files: list[str] = []
101
102
103 def _cleanup_temp_files() -> None:
104 """Remove temporary files created by :func:`_download_uri`."""
105 for path in _temp_files:
106 pathlib.Path(path).unlink(missing_ok=True)
107 _temp_files.clear()
108
109
110 atexit.register(_cleanup_temp_files)
111
112
113 def _save_registry_state() -> _RegistryState:
114 """Snapshot the current registry state for later restoration."""
115 return {
116 'ext': _custom_ext_readers.copy(),
117 'sources': _custom_ext_reader_sources.copy(),
118 'pending': {k: list(v) for k, v in _pending_ext_readers.items()},
119 'entry_points_loaded': _entry_points_loaded,
120 }
121
122
123 def _restore_registry_state(state: _RegistryState) -> None:
124 """Restore registry state from a snapshot."""
125 global _entry_points_loaded # noqa: PLW0603
126 _custom_ext_readers.clear()
127 _custom_ext_readers.update(state['ext'])
128 _custom_ext_reader_sources.clear()
129 _custom_ext_reader_sources.update(state['sources'])
130 _pending_ext_readers.clear()
131 _pending_ext_readers.update({k: list(v) for k, v in state['pending'].items()})
132 _entry_points_loaded = state['entry_points_loaded']
133
134
135 def has_scheme(value: str) -> bool:
136 """Return ``True`` if *value* starts with a URI scheme (e.g. ``https://``).
137
138 Parameters
139 ----------
140 value : str
141 The string to check.
142
143 Returns
144 -------
145 bool
146 ``True`` if *value* contains a ``://`` scheme prefix before
147 the first ``/``.
148
149 """
150 # Check that :// appears before the first / to avoid false positives
151 # on paths like /data/re://fresh/mesh.vtu
152 slash = value.find('/')
153 colon = value.find('://')
154 return colon > 0 and (slash == -1 or colon < slash)
155
156
157 def _download_uri(uri: str, ext: str) -> str:
158 """Download a remote URI to a temporary file, preserving *ext*.
159
160 Uses ``fsspec`` when available (supports ``s3://``, ``gs://``,
161 ``az://``, ``http://``, and any other registered filesystem).
162 Falls back to ``pooch`` for ``http://`` and ``https://`` URIs.
163
164 Parameters
165 ----------
166 uri : str
167 The remote URI to download.
168 ext : str
169 File extension to use for the temp file (e.g. ``'.vtu'``).
170
171 Returns
172 -------
173 str
174 Path to the downloaded temporary file.
175
176 Raises
177 ------
178 ImportError
179 If the URI scheme requires ``fsspec`` and it is not installed.
180 ConnectionError
181 If the download fails.
182
183 """
184 suffix = ext or ''
185 try:
186 import fsspec # noqa: PLC0415 — optional dependency
187 except ImportError:
188 if not uri.lower().startswith(('http://', 'https://')):
189 scheme = uri.split('://', maxsplit=1)[0]
190 msg = (
191 f'Cannot download "{scheme}://" URIs without fsspec. '
192 f'Install it with: pip install fsspec'
193 )
194 raise ImportError(msg)
195 result = pooch.retrieve(uri, known_hash=None, fname=f'pyvista_download{suffix}') # type: ignore[attr-defined] # pooch doesn't export retrieve in __all__
196 _temp_files.append(result)
197 return result
198
199 try:
200 with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
201 tmp_name = tmp.name
202 _temp_files.append(tmp_name)
203 with fsspec.open(uri, 'rb') as remote, pathlib.Path(tmp_name).open('wb') as local:
204 shutil.copyfileobj(remote, local)
205 except Exception as e:
206 msg = f'Failed to download "{uri}": {e}'
207 raise ConnectionError(msg) from e
208 else:
209 return tmp_name
210
211
212 @overload
213 def register_reader(
214 key: str,
215 handler: None = None,
216 *,
217 override: bool = False,
218 ) -> Callable[[ReaderHandler], ReaderHandler]: ...
219
220
221 @overload
222 def register_reader(
223 key: str,
224 handler: ReaderHandler,
225 *,
226 override: bool = False,
227 ) -> None: ...
228
229
230 def register_reader(
231 key: str,
232 handler: ReaderHandler | None = None,
233 *,
234 override: bool = False,
235 ) -> Callable[[ReaderHandler], ReaderHandler] | None:
236 """Register a custom reader for a file extension.
237
238 Can be used as a plain call or as a decorator.
239
240 .. versionadded:: 0.48.0
241
242 Parameters
243 ----------
244 key : str
245 A file extension (e.g. ``'.myformat'``).
246
247 handler : callable, optional
248 A callable with signature ``handler(path: str, **kwargs)`` that
249 returns a :class:`pyvista.DataSet`. When omitted the function
250 acts as a decorator and returns the decorated callable unchanged.
251
252 override : bool, default: False
253 If ``True``, allow overriding a built-in VTK reader for this
254 extension and silence the warning that would otherwise fire when
255 replacing an existing custom registration.
256
257 Returns
258 -------
259 callable or None
260 When used as a decorator (``handler`` omitted), returns the
261 decorated function. Otherwise returns ``None``.
262
263 Raises
264 ------
265 ValueError
266 If ``key`` collides with a built-in VTK reader and *override*
267 is ``False``.
268
269 Warns
270 -----
271 UserWarning
272 If ``key`` already refers to a registered custom reader. The new
273 registration replaces the old one (last wins); pass
274 ``override=True`` to silence the warning.
275
276 See Also
277 --------
278 pyvista.register_writer
279 Sibling API for registering custom writers.
280 pyvista.registered_readers
281 Introspect every registered reader.
282
283 Examples
284 --------
285 Register a reader for a custom file extension.
286
287 >>> import pyvista as pv
288 >>> def my_reader(path, **kwargs): ...
289 >>> pv.register_reader('.myformat', my_reader) # doctest: +SKIP
290
291 Use as a decorator.
292
293 >>> @pv.register_reader('.myformat') # doctest: +SKIP
294 ... def my_reader(path, **kwargs): ...
295
296 """
297 if handler is None:
298 # Decorator form: @pv.register_reader('.ext')
299 def _decorator(fn: ReaderHandler) -> ReaderHandler:
300 _register(key, fn, override=override)
301 return fn
302
303 return _decorator
304
305 _register(key, handler, override=override)
306 return None
307
308
309 def _register(
310 key: str,
311 handler: ReaderHandler,
312 *,
313 override: bool = False,
314 source: str | None = None,
315 ) -> None:
316 """Register a handler in the extension registry."""
317 key = key.lower()
318 if not key.startswith('.'):
319 key = f'.{key}'
320 if not override and key in CLASS_READERS:
321 msg = (
322 f'Cannot register custom reader for "{key}": '
323 f'collides with built-in VTK reader. '
324 f'Use override=True to replace it.'
325 )
326 raise ValueError(msg)
327 if not override and key in _custom_ext_readers:
328 existing_source = _custom_ext_reader_sources.get(key, '<unknown>')
329 warn_external(
330 f'Registering reader for "{key}" replaces an existing custom '
331 f'reader from {existing_source}.',
332 )
333 _custom_ext_readers[key] = handler
334 _custom_ext_reader_sources[key] = source if source is not None else handler_source(handler)
335
336
337 def _get_ext_handler(ext: str) -> ReaderHandler | None:
338 """Look up a custom extension handler, importing the plugin lazily.
339
340 Built-in extensions never trigger entry-point plugin imports — only
341 extensions that an installed plugin has actually claimed do.
342 """
343 handler = _custom_ext_readers.get(ext)
344 if handler is not None:
345 return handler
346 _ensure_entry_points()
347 if ext in _pending_ext_readers:
348 _resolve_pending_reader(ext)
349 return _custom_ext_readers.get(ext)
350
351
352 def _ensure_entry_points() -> None:
353 """Scan ``pyvista.readers`` entry-point metadata once.
354
355 Populates :data:`_pending_ext_readers` with every extension declared
356 by an installed plugin. The plugin modules themselves are **not**
357 imported here; the cost is one ``importlib.metadata.entry_points``
358 call. Plugin imports are deferred to :func:`_resolve_pending_reader`,
359 which runs only when a reader for that specific extension is
360 actually requested.
361 """
362 global _entry_points_loaded # noqa: PLW0603
363 if _entry_points_loaded:
364 return
365 _entry_points_loaded = True
366
367 for ep in entry_points(group='pyvista.readers'):
368 key = ep.name.lower()
369 if not key.startswith('.'):
370 key = f'.{key}'
371 if key in _custom_ext_readers:
372 continue
373 _pending_ext_readers.setdefault(key, []).append(ep)
374
375
376 def _resolve_pending_reader(ext: str) -> bool:
377 """Import the plugin claiming *ext*, if any.
378
379 Returns
380 -------
381 bool
382 ``True`` if a plugin loaded successfully for ``ext``. ``False``
383 if no pending plugin matches, or if the plugin failed to import.
384
385 Notes
386 -----
387 A plugin that fails to import emits a ``UserWarning`` and is dropped
388 from the pending list, so subsequent lookups of the same extension
389 fall straight through without re-triggering the import or
390 re-emitting the warning.
391
392 """
393 eps = _pending_ext_readers.pop(ext, None)
394 if not eps:
395 return False
396 winner = eps[0]
397 try:
398 # ep.load() runs third-party import machinery — it can raise
399 # literally anything. Convert to a warning so one broken plugin
400 # cannot take down every pyvista.read call.
401 handler = winner.load()
402 except Exception as err: # noqa: BLE001
403 warn_external(
404 f'Failed to load pyvista.readers entry point "{winner.value}" for "{ext}": {err}'
405 )
406 return False
407 _custom_ext_readers[ext] = handler
408 _custom_ext_reader_sources[ext] = winner.value
409 if len(eps) > 1:
410 providers = ', '.join(ep.value for ep in eps)
411 warn_external(
412 f'Multiple pyvista.readers entry points registered for '
413 f'"{ext}": {providers}. Using {winner.value}.'
414 )
415 return True
416
417
418 def _list_custom_exts() -> list[str]:
419 """Return the list of extensions with registered custom readers.
420
421 Triggers lazy entry-point *metadata* discovery so that extensions
422 contributed by installed packages appear in listings of supported
423 formats. The plugin modules themselves are **not** imported.
424 """
425 _ensure_entry_points()
426 return list(_custom_ext_readers.keys() | _pending_ext_readers.keys())
427
428
429 def registered_readers() -> tuple[ReaderRegistration, ...]:
430 """Return every custom reader currently registered.
431
432 Forces discovery of any pending entry-point plugins so the returned
433 list reflects every reader visible to PyVista. A plugin that fails to
434 import emits a ``UserWarning`` and is skipped; the rest still appear
435 in the result.
436
437 .. versionadded:: 0.48.0
438
439 Returns
440 -------
441 tuple[ReaderRegistration, ...]
442 One record per registered extension. Each record exposes
443 ``extension``, ``handler``, and ``source``.
444
445 Examples
446 --------
447 >>> import pyvista as pv
448 >>> def my_reader(path, **kwargs): ...
449 >>> pv.register_reader('.demo_reader', my_reader)
450 >>> [
451 ... r.extension
452 ... for r in pv.registered_readers()
453 ... if r.extension == '.demo_reader'
454 ... ]
455 ['.demo_reader']
456
457 """
458 _ensure_entry_points()
459 for ext in list(_pending_ext_readers):
460 _resolve_pending_reader(ext)
461 return tuple(
462 ReaderRegistration(
463 extension=ext,
464 handler=handler,
465 source=_custom_ext_reader_sources.get(ext, '<unknown>'),
466 )
467 for ext, handler in _custom_ext_readers.items()
468 )