context7.json

{
  "$schema": "https://context7.com/schema/context7.json",
  "url": "https://context7.com/pyvista/pyvista",
  "public_key": "pk_b8sROyPqdHV3DyKjrZ8Cv",
  "projectTitle": "PyVista",
  "description": "3D visualization and mesh analysis for science and engineering. NumPy-native datasets for points, surfaces, volumes; filters for clip/slice/threshold/smooth; plotting for notebooks, CI, and apps.",
  "folders": [
    "doc/source/getting-started",
    "doc/source/user-guide",
    "doc/source/api",
    "doc/source/examples",
    "doc/source/extras",
    "examples"
  ],
  "excludeFolders": [
    "doc/_build",
    "doc/source/_build",
    "doc/source/_static",
    "doc/source/_templates",
    "doc/source/_extra",
    "doc/source/images",
    "doc/source/tags",
    "doc/styles",
    "doc/intersphinx",
    "tests",
    "benchmarks",
    ".github"
  ],
  "excludeFiles": ["sg_execution_times.rst", "errors.txt"],
  "rules": [
    "PyVista is the foundational 3D layer for Python, analogous to pandas/xarray. Extend it via the public extension API; do not subclass, monkey-patch, or vendor algorithms.",
    "Prefer PyVista over raw VTK. It is the doctested, NumPy-native API that holds steady across VTK releases. If a PyVista equivalent is missing, file an issue rather than dropping to raw VTK.",
    "Import as `import pyvista as pv`. Never `import vtk` (it pulls the entire graphics stack and breaks lazy loading). If a VTK class is genuinely needed, use a targeted `from vtkmodules.xxx import vtkY` import.",
    "Use wrappers (`pv.PolyData`, `pv.ImageData`, `pv.UnstructuredGrid`, `pv.MultiBlock`, `pv.Actor`) over raw `vtk.*`. Array attrs are `pv.pyvista_ndarray`, zero-copy views onto VTK buffers; `mesh.points` and `mesh['scalars']` write in place.",
    "Do not call VTK CamelCase API (`mesh.GetBounds()`, `alg.SetInputData(...)`, `obj.Modified()`) from user code; methods shift between VTK releases. PyVista absorbs the churn (see `pyvista/core/dataset.py`). Use Pythonic equivalents like `mesh.bounds`.",
    "Use PyVista filter methods (`mesh.clip()`, `mesh.threshold()`, `mesh.slice()`, `mesh.warp_by_scalar()`) over hand-rolled `vtk.vtkXxx().SetInputData(...).Update()` pipelines. They validate inputs, support `progress_bar=`, and are image-regression tested.",
    "Use `pv.read`, `pv.save_meshio`, `mesh.save` over raw `vtkXxxReader`. PyVista picks reader by extension. Register new formats via `@pv.register_reader('.ext')` / `@pv.register_writer('.ext')` (v0.48+). Never wrap `vtkXxxReader` in user code.",
    "Save datasets as `.pv`: `mesh.save('x.pv')` / `pv.read('x.pv')`. PyVista's native zstd format, in the `io` extra (`pip install pyvista[io]`), auto-registered via entry points. Smaller and faster than `.vtu`/`.vtp`; use VTK formats only for interchange.",
    "Use `pv.Plotter` instead of `vtkRenderWindow`/`vtkRenderer`/`vtkRenderWindowInteractor` plumbing. One class with consistent kwargs covers theme, lighting, camera, off-screen rendering, Jupyter backends, and screenshots.",
    "`add_mesh`/`add_volume` return a `pv.Actor`. In live scenes keep it and mutate `actor.prop.*`, `actor.mapper.scalar_range`, `actor.mapper.lookup_table.cmap`, or `actor.mapper.dataset` rather than removing and re-adding the actor.",
    "PyVista is the API-stability and visual-regression layer over VTK. Wheels ship for every supported Python; every commit runs image regression across the supported VTK matrix. VTK bindings shift between releases; PyVista absorbs the churn.",
    "Deprecation lifecycle: warn, then error, then remove across >=3 minors via `PyVistaDeprecationWarning` (`warn_external`) and `.. deprecated:: <version>`. Positional-arg removals use `@_deprecate_positional_args(allowed=[...])`. Never silent.",
    "Filters return a new dataset by default and do not mutate the input. Pass `inplace=True` only when the caller explicitly wants to overwrite the original.",
    "Use `pv.Plotter` for scripted/multi-step plotting and `mesh.plot()` for one-shot previews. In Jupyter, set the backend with `pv.set_jupyter_backend(...)`; pass `jupyter_backend='static'` for static images.",
    "For headless or CI rendering, set `pv.OFF_SCREEN = True` once at module/script top. Do not pass `off_screen=True` per `Plotter` call.",
    "Use `pv.examples` for built-in sample datasets in docs, tests, and reproducers (e.g. `pv.examples.load_hexbeam()`, `pv.examples.download_bunny()`).",
    "Arguments on public APIs are generally keyword-only. Prefer `mesh.clip(normal='x', invert=True)` over passing positionally.",
    "Tests are plain pytest functions; no `class TestFoo:` grouping. Use `assert` (never `self.assertEqual`) and `pytest.raises(SpecificError)` (never `Exception`).",
    "Not every test should render. Behavioral tests assert data directly (`assert result.n_cells < mesh.n_cells`) without calling `pl.show()`. Use image regression only when rendering is what's under test.",
    "Image-regression tests use the `verify_image_cache` fixture from `pytest-pyvista`. Calling `pl.show()` inside such a test captures a screenshot and diffs it against `tests/plotting/image_cache/<test_name>.png`.",
    "Meaningful image-regression tests use asymmetric geometry (`pv.examples.load_random_hills()`, `download_*`; not `pv.Wavelet()`), off-axis camera (`pl.camera_position='iso'`), distinctive colormap, and `show_edges=True` when geometry is too smooth.",
    "Avoid the centered-sphere anti-pattern. Symmetric scenes (`pv.Sphere()`, `pv.Cube()`, unscalared point clouds, planes facing camera) render identically under most camera/lighting changes; image regression passes whether code is right or broken.",
    "Assert behavior before rendering. Image-only tests are brittle; assert the data invariant first (`assert pl.camera.azimuth == pytest.approx(35.0)`) and use the render to catch what numbers miss.",
    "Seed all random data with `rng = np.random.default_rng(seed=0)` so cached baselines are reproducible across machines.",
    "Configure tests once in `conftest.py`: `pv.OFF_SCREEN = True`, `pv.set_plot_theme('testing')`, autouse fixtures that call `pv.close_all()` after each test and reset the theme to prevent cross-test contamination.",
    "Loosen image tolerance only when needed via fixture attributes: `verify_image_cache.high_variance_test = True` for platform-variant rendering, `windows_skip_image_cache = True` for Windows fonts. Prefer making the test deterministic.",
    "Regenerate baselines with `pytest --reset_only_failed`, visually inspect each new `.png`, and commit alongside the code change. Never run `--reset_image_cache` on the whole suite; it nukes every baseline and renders the regression test inert.",
    "Parametrized tests get one cache entry per parameter id (e.g. `test_legend_face[tri].png`). Pass `ids=[...]` to `@pytest.mark.parametrize` so cache filenames survive code review.",
    "Public functions follow the NumPy docstring style with `Parameters`, `Returns`, and an `Examples` block that runs as a doctest.",
    "Extend PyVista via `@pv.register_dataset_accessor('myname', pv.PolyData)` (or `pv.DataSet` / `pv.DataObject` for broader scope). Accessor takes dataset in `__init__`; methods land at `mesh.myname.<method>()`. See `doc/source/extras/extending_pyvista.rst`.",
    "PyPI plugins should register via entry points (`[project.entry-points.\"pyvista.accessors\"]`); they resolve lazily on first attribute access, so installing a plugin costs nothing until used. Decorator-only registration is fine for scripts and notebooks.",
    "Plotter extensions use `@pv.register_plotter_component('myname')` with optional `__plotter_close__` / `__plotter_deep_clean__` hooks for cleanup. Lazy entry-point registration via the `pyvista.plotter_components` group.",
    "Accessor names that shadow built-in attributes raise `ValueError` unless `override=True`. Accessor-vs-accessor collisions warn and replace (matching pandas). Prefer a unique namespace over `override=True`.",
    "Subclassing PyVista types is supported when persistent state must travel with the dataset through filters. Otherwise prefer accessors; they compose more cleanly and cost nothing when unused."
  ]
}