Register PyVista dataset accessor (#114)

* Register PyVista dataset accessor

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: banesullivan

pyproject.toml

@@ -27,6 +27,11 @@ readme = "README.rst"
 requires-python = ">=3.10"
 version = "0.9.dev0"
 
+[project.entry-points."pyvista.accessors"]
+# Value points at the plugin module; importing it runs the
+# ``@register_dataset_accessor`` decorator as a side effect.
+tetgen = "tetgen._accessor"
+
 [project.optional-dependencies]
 docs = [
   "pyvista",

src/tetgen/_accessor.py

@@ -0,0 +1,90 @@
+"""Register a ``.tetgen`` accessor on :class:`pyvista.PolyData`.
+
+Importing this module (which :mod:`tetgen` does on package import)
+attaches a :class:`TetGenAccessor` so every :class:`~pyvista.PolyData`
+instance exposes the ``.tetgen`` namespace.
+
+Requires PyVista >= 0.48, which introduced ``register_dataset_accessor``.
+On older versions importing this module is a no-op.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Any
+
+import pyvista as pv
+
+if TYPE_CHECKING:
+    from tetgen.pytetgen import TetGen
+
+
+HAS_ACCESSOR_REGISTRY = hasattr(pv, "register_dataset_accessor")
+
+
+def _register(cls):
+    if HAS_ACCESSOR_REGISTRY:
+        return pv.register_dataset_accessor("tetgen", pv.PolyData)(cls)
+    return cls
+
+
+@_register
+class TetGenAccessor:
+    """Tetrahedralization accessor for surface meshes.
+
+    Wraps the :class:`tetgen.TetGen` tetrahedralizer so a PyVista user
+    can call it directly on any :class:`~pyvista.PolyData` surface::
+
+        import pyvista as pv
+        import tetgen  # noqa: F401 — registers the ``.tetgen`` accessor
+
+        grid = pv.Sphere().tetgen.tetrahedralize(order=1, mindihedral=20)
+
+    The underlying :class:`~tetgen.TetGen` instance is constructed
+    lazily on first use and cached. Access it via :attr:`instance`
+    when you need the lower-level API (raw arrays, markers, edges).
+    """
+
+    def __init__(self, mesh: pv.PolyData) -> None:
+        """Bind the accessor to its parent :class:`~pyvista.PolyData`."""
+        self._mesh = mesh
+        self._tetgen: TetGen | None = None
+
+    @property
+    def instance(self) -> TetGen:
+        """Return the underlying :class:`tetgen.TetGen` object.
+
+        Constructed lazily on first access. Use this for the raw array
+        outputs (``node``, ``elem``, ``triface_markers``) or the
+        ``.make_manifold()`` preprocessor.
+        """
+        if self._tetgen is None:
+            from tetgen import TetGen  # noqa: PLC0415
+
+            self._tetgen = TetGen(self._mesh)
+        return self._tetgen
+
+    def tetrahedralize(self, **kwargs: Any) -> pv.UnstructuredGrid:
+        """Tetrahedralize the surface mesh and return the volume grid.
+
+        Forwards all keyword arguments to
+        :meth:`tetgen.TetGen.tetrahedralize`. Returns the resulting
+        :class:`~pyvista.UnstructuredGrid` directly so the call chains
+        cleanly with PyVista filters::
+
+            pv.Sphere().tetgen.tetrahedralize(order=1).extract_cells([0, 1, 2])
+
+        See :meth:`tetgen.TetGen.tetrahedralize` for the full parameter
+        list.
+        """
+        self.instance.tetrahedralize(**kwargs)
+        return self.instance.grid
+
+    def make_manifold(self, **kwargs: Any) -> pv.PolyData:
+        """Repair non-manifold input and return the cleaned surface.
+
+        Forwards to :meth:`tetgen.TetGen.make_manifold`. See that
+        method's docstring for parameters.
+        """
+        self.instance.make_manifold(**kwargs)
+        return self.instance.mesh

tests/test_accessor.py

@@ -0,0 +1,76 @@
+"""Tests for the ``.tetgen`` accessor registered on :class:`pyvista.PolyData`."""
+
+from __future__ import annotations
+
+import pytest
+import pyvista as pv
+
+import tetgen
+import tetgen._accessor  # noqa: F401 — registers the ``.tetgen`` accessor
+
+pytestmark = pytest.mark.skipif(
+    not tetgen._accessor.HAS_ACCESSOR_REGISTRY,
+    reason="requires pyvista >= 0.48 dataset accessor registry",
+)
+
+
+def test_accessor_attached_on_polydata():
+    assert hasattr(pv.Sphere(), "tetgen")
+
+
+def test_accessor_not_attached_on_non_polydata():
+    # Grid/ImageData types should not expose a surface-mesh accessor.
+    assert not hasattr(pv.ImageData(), "tetgen")
+    assert not hasattr(pv.UnstructuredGrid(), "tetgen")
+
+
+def test_accessor_cached_per_instance():
+    sphere = pv.Sphere()
+    assert sphere.tetgen is sphere.tetgen
+
+
+def test_tetrahedralize_returns_unstructured_grid():
+    sphere = pv.Sphere(theta_resolution=10, phi_resolution=10)
+    grid = sphere.tetgen.tetrahedralize(order=1, mindihedral=20, minratio=1.5)
+    assert isinstance(grid, pv.UnstructuredGrid)
+    assert grid.n_cells > 0
+    assert grid.n_points > 0
+
+
+def test_tetrahedralize_matches_direct_api():
+    sphere = pv.Sphere(theta_resolution=10, phi_resolution=10)
+    direct = tetgen.TetGen(sphere)
+    direct.tetrahedralize(order=1, mindihedral=20, minratio=1.5)
+    direct_grid = direct.grid
+
+    accessor_grid = sphere.tetgen.tetrahedralize(order=1, mindihedral=20, minratio=1.5)
+    assert accessor_grid.n_cells == direct_grid.n_cells
+    assert accessor_grid.n_points == direct_grid.n_points
+
+
+def test_instance_lazy_and_cached():
+    sphere = pv.Sphere()
+    accessor = sphere.tetgen
+    first = accessor.instance
+    second = accessor.instance
+    assert first is second
+    assert isinstance(first, tetgen.TetGen)
+
+
+def test_chains_with_core_filters():
+    """Accessor result chains cleanly with a core PyVista filter."""
+    grid = (
+        pv.Sphere(theta_resolution=10, phi_resolution=10)
+        .tetgen.tetrahedralize(order=1)
+        .extract_cells([0, 1, 2])
+    )
+    assert isinstance(grid, pv.UnstructuredGrid)
+    assert grid.n_cells == 3
+
+
+def test_registered_record_reports_tetgen_as_source():
+    records = [r for r in pv.registered_accessors() if r.name == "tetgen"]
+    assert len(records) == 1
+    record = records[0]
+    assert record.target is pv.PolyData
+    assert record.source.startswith("tetgen._accessor")