Merge branch 'main' into maint/fix_minor_doc_noise

* upstream/main:
  Add setup and teardown functionality to plot_directive (pyvista#2907)
  Update hypothesis requirement from <6.48.4 to <6.49.2 (pyvista#2942)
  Bump lxml from 4.9.0 to 4.9.1 (pyvista#2936)
  Bump typing-extensions from 4.2.0 to 4.3.0 (pyvista#2939)
  Update hypothesis requirement from <6.48.3 to <6.48.4 (pyvista#2938)
  Bump trimesh from 3.12.6 to 3.12.7 (pyvista#2937)
  Update information of release (pyvista#2911)
  update pre-commit hooks (pyvista#2931)
  Handle invalid theme on init (pyvista#2917)
  Add `py.typed` Marker (pyvista#2904)
  [create-pull-request] update local intersphinx (pyvista#2926)
  Add tags with python commands to avoid misnumbering (pyvista#2416)
  Fix the url link of discretize (pyvista#2914)
  Add DataSet.cell_point_ids (pyvista#2897)
  Update hypothesis requirement from <6.48.2 to <6.48.3 (pyvista#2918)
  Ensure data remains a shallow copy when added to plotter (pyvista#2888)

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/psf/black
-  rev: 22.3.0
+  rev: 22.6.0
   hooks:
   - id: black
 
@@ -57,6 +57,6 @@ repos:
 
 # this validates our github workflow files
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.16.1
+  rev: 0.16.2
   hooks:
     - id: check-github-workflows

CONTRIBUTING.rst

@@ -415,16 +415,16 @@ The main features of our branching model are:
    version of the code base that is also reflected on PyPI/. Hotfixes
    from ``fix/`` branches should be merged both to main and to these
    branches. When necessary to create a new patch release these release
-   branches will have their ``__version__.py`` updated and be tagged
-   with a patched semantic version (e.g. ``0.24.1``). This triggers CI
+   branches will have their ``pyvista/_version.py`` updated and be tagged
+   with a semantic version (e.g. ``v0.24.1``). This triggers CI
    to push to PyPI, and allow us to rapidly push hotfixes for past
    versions of ``pyvista`` without having to worry about untested
    features.
 -  When a minor release candidate is ready, a new ``release`` branch
    will be created from ``main`` with the next incremented minor version
    (e.g. ``release/0.25``), which will be thoroughly tested. When deemed
    stable, the release branch will be tagged with the version
-   (``0.25.0`` in this case), and if necessary merged with main if any
+   (``v0.25.0`` in this case), and if necessary merged with main if any
    changes were pushed to it. Feature development then continues on
    ``main`` and any hotfixes will now be merged with this release. Older
    release branches should not be deleted so they can be patched as
@@ -457,24 +457,26 @@ created the following will occur:
 4.  After building the documentation, open the local build and examine
     the examples gallery for any obvious issues.
 
-5.  Update the version numbers in ``pyvista/_version.py`` and commit it.
-    Push the branch to GitHub and create a new PR for this release that
-    merges it to main. Development to main should be limited at this
-    point while effort is focused on the release.
+5.  Update the development version numbers in ``pyvista/_version.py``
+    and commit it (e.g. ``0, 26, 'dev0'``). Push the branch to GitHub
+    and create a new PR for this release that merges it to main.
+    Development to main should be limited at this point while effort
+    is focused on the release.
 
 6.  It is now the responsibility of the ``pyvista`` community to
     functionally test the new release. It is best to locally install
     this branch and use it in production. Any bugs identified should
     have their hotfixes pushed to this release branch.
 
 7.  When the branch is deemed as stable for public release, the PR will
-    be merged to main and the ``main`` branch will be tagged with a
-    ``MAJOR.MINOR.0`` release. The release branch will not be deleted.
-    Tag the release with:
+    be merged to main. After update the version number in
+    ``release/MAJOR.MINOR`` branch, the ``release/MAJOR.MINOR`` branch
+    will be tagged with a ``vMAJOR.MINOR.0`` release. The release branch
+    will not be deleted. Tag the release with:
 
     .. code:: bash
 
-       git tag MAJOR.MINOR.0
+       git tag v$(python -c "import pyvista as pv; print(pv.__version__)")
        git push origin --tags
 
 8.  Create a list of all changes for the release. It is often helpful to
@@ -508,7 +510,7 @@ should not wait until a minor release. The steps for a patch release
    will generally be the latest release branch (e.g. ``release/0.25``).
 
 2. Update ``pyvista/_version.py`` with the next patch increment (e.g.
-   ``0.25.1``), commit it, and open a PR that merge with the release
+   ``v0.25.1``), commit it, and open a PR that merge with the release
    branch. This gives the ``pyvista`` community a chance to validate and
    approve the bugfix release. Any additional hotfixes should be outside
    of this PR.

MANIFEST.in

@@ -2,3 +2,6 @@
 include LICENSE
 recursive-exclude doc *.rst
 recursive-exclude doc *.py
+# Include type hinting files
+global-include *.pyi
+global-include *.typed

doc/conf.py

@@ -351,6 +351,13 @@ def __repr__(self):
 IMPORT_PYVISTA_RE = r'\b(import +pyvista|from +pyvista +import)\b'
 IMPORT_MATPLOTLIB_RE = r'\b(import +matplotlib|from +matplotlib +import)\b'
 
+plot_setup = """
+from pyvista import set_plot_theme as __s_p_t
+__s_p_t('document')
+del __s_p_t
+"""
+plot_cleanup = plot_setup
+
 
 def _str_examples(self):
     examples_str = "\n".join(self['Examples'])

doc/extras/plot_directive.rst

@@ -3,7 +3,7 @@
 Sphinx PyVista Plot Directive
 =============================
 You can generate static images of pyvista plots using the
-``.. pyvista-plot`` directive by adding the following to your
+``.. pyvista-plot::`` directive by adding the following to your
 ``conf.py`` when building your documentation using Sphinx.
 
 .. code:: python
@@ -14,7 +14,7 @@ You can generate static images of pyvista plots using the
    ]
 
 You can then issue the plotting directive within your sphinx
-documentation files:
+documentation files::
 
    .. pyvista-plot::
       :caption: A sphere

doc/make_external_gallery.py

@@ -60,7 +60,7 @@ def format(self):
     discretize=Example(
         title="3D Rendering with Discretize",
         description="3D Rendering with Discretize",
-        link="http://discretize.simpeg.xyz/en/master/examples/plot_pyvista_laguna.html",
+        link="http://discretize.simpeg.xyz/en/main/examples/plot_pyvista_laguna.html",
         image="discretize.png",
     ),
     open_foam=Example(

pyvista/__init__.py

@@ -12,7 +12,7 @@
 from pyvista.plotting import *
 from pyvista.utilities import *
 from pyvista.core import *
-from pyvista.utilities.misc import _get_vtk_id_type, vtk_version_info
+from pyvista.utilities.misc import _get_vtk_id_type, vtk_version_info, _set_plot_theme_from_env
 from pyvista import _vtk
 from pyvista.jupyter import set_jupyter_backend, PlotterITK
 from pyvista.themes import set_plot_theme, load_theme, _rcParams
@@ -27,8 +27,7 @@
 rcParams = _rcParams()  # raises DeprecationError when used
 
 # Set preferred plot theme
-if 'PYVISTA_PLOT_THEME' in os.environ:
-    set_plot_theme(os.environ['PYVISTA_PLOT_THEME'].lower())
+_set_plot_theme_from_env()
 
 # get the int type from vtk
 ID_TYPE = _get_vtk_id_type()

pyvista/core/dataset.py

@@ -2538,3 +2538,33 @@ def cell_type(self, ind: int) -> int:
 
         """
         return self.GetCellType(ind)
+
+    def cell_point_ids(self, ind: int) -> List[int]:
+        """Return the point ids in a cell.
+
+        Parameters
+        ----------
+        ind : int
+            Cell ID.
+
+        Returns
+        -------
+        list[int]
+            Point Ids that are associated with the cell.
+
+        Examples
+        --------
+        >>> from pyvista import examples
+        >>> mesh = examples.load_airplane()
+        >>> mesh.cell_type(0)
+        5
+
+        Cell type 5 is a triangular cell with three points.
+
+        >>> mesh.cell_point_ids(0)
+        [0, 1, 2]
+
+        """
+        cell = self.GetCell(ind)
+        point_ids = cell.GetPointIds()
+        return [point_ids.GetId(i) for i in range(point_ids.GetNumberOfIds())]

pyvista/ext/plot_directive.py

@@ -3,7 +3,7 @@
 A directive for including a PyVista plot in a Sphinx document
 =============================================================
 
-The `.. pyvista-plot::` sphinx directive will include an inline
+The ``.. pyvista-plot::`` sphinx directive will include an inline
 ``.png`` image.
 
 The source code for the plot may be included in one of two ways:
@@ -75,19 +75,28 @@
 ---------------------
 The plot directive has the following configuration options:
 
-    plot_include_source
-        Default value for the include-source option.
+    plot_include_source : bool
+        Default value for the include-source option. Default is ``True``.
 
-    plot_basedir
+    plot_basedir : str
         Base directory, to which ``plot::`` file names are relative
-        to.  (If ``None`` or empty, file names are relative to the
-        directory where the file containing the directive is.)
+        to.  If ``None`` or unset, file names are relative to the
+        directory where the file containing the directive is.
 
-    plot_html_show_formats
-        Whether to show links to the files in HTML.
+    plot_html_show_formats : bool
+        Whether to show links to the files in HTML. Default ``True``.
 
-    plot_template
-        Provide a customized template for preparing restructured text.
+    plot_template : str
+        Provide a customized Jinja2 template for preparing restructured text.
+
+    plot_setup : str
+        Python code to be run before every plot directive block.
+
+    plot_cleanup : str
+        Python code to be run after every plot directive block.
+
+These options can be set by defining global variables of the same name in
+:file:`conf.py`.
 
 """
 
@@ -183,6 +192,8 @@ def setup(app):
     app.add_config_value('plot_basedir', None, True)
     app.add_config_value('plot_html_show_formats', True, True)
     app.add_config_value('plot_template', None, True)
+    app.add_config_value('plot_setup', None, True)
+    app.add_config_value('plot_cleanup', None, True)
     return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': pyvista.__version__}
 
 
@@ -331,7 +342,8 @@ def render_figures(
     """Run a pyplot script and save the images in *output_dir*.
 
     Save the images under *output_dir* with file names derived from
-    *output_base*
+    *output_base*. Closed plotters are ignored if they were never
+    rendered.
     """
     # Try to determine if all images already exist
     is_doctest, code_pieces = _split_code_at_show(code)
@@ -340,30 +352,45 @@ def render_figures(
     results = []
     ns = plot_context if context else {}
 
-    for i, code_piece in enumerate(code_pieces):
-        # generate the plot
-        _run_code(
-            doctest.script_from_examples(code_piece) if is_doctest else code_piece,
-            code_path,
-            ns,
-            function_name,
-        )
+    # Check for setup and teardown code for plots
+    code_setup = config.plot_setup
+    code_cleanup = config.plot_cleanup
 
-        images = []
-        figures = pyvista.plotting._ALL_PLOTTERS
+    if code_setup:
+        _run_code(code_setup, code_path, ns, function_name)
 
-        for j, (_, plotter) in enumerate(figures.items()):
-            if hasattr(plotter, '_gif_filename'):
-                image_file = ImageFile(output_dir, f"{output_base}_{i:02d}_{j:02d}.gif")
-                shutil.move(plotter._gif_filename, image_file.filename)
-            else:
-                image_file = ImageFile(output_dir, f"{output_base}_{i:02d}_{j:02d}.png")
-                plotter.screenshot(image_file.filename)
-            images.append(image_file)
-
-        pyvista.close_all()  # close and clear all plotters
+    try:
+        for i, code_piece in enumerate(code_pieces):
+            # generate the plot
+            _run_code(
+                doctest.script_from_examples(code_piece) if is_doctest else code_piece,
+                code_path,
+                ns,
+                function_name,
+            )
 
-        results.append((code_piece, images))
+            images = []
+            figures = pyvista.plotting._ALL_PLOTTERS
+
+            for j, (_, plotter) in enumerate(figures.items()):
+                if hasattr(plotter, '_gif_filename'):
+                    image_file = ImageFile(output_dir, f"{output_base}_{i:02d}_{j:02d}.gif")
+                    shutil.move(plotter._gif_filename, image_file.filename)
+                else:
+                    image_file = ImageFile(output_dir, f"{output_base}_{i:02d}_{j:02d}.png")
+                    try:
+                        plotter.screenshot(image_file.filename)
+                    except RuntimeError:  # pragma no cover
+                        # ignore closed, unrendered plotters
+                        continue
+                images.append(image_file)
+
+            pyvista.close_all()  # close and clear all plotters
+
+            results.append((code_piece, images))
+    finally:
+        if code_cleanup:
+            _run_code(code_cleanup, code_path, ns, function_name)
 
     return results
 

pyvista/py.typed

@@ -0,0 +1 @@
+partial\n

pyvista/utilities/misc.py

@@ -1,12 +1,29 @@
 """Miscellaneous pyvista functions."""
 from collections import namedtuple
+import os
 import warnings
 
 import numpy as np
 
 from pyvista import _vtk
 
 
+def _set_plot_theme_from_env():
+    """Set plot theme from an environment variable."""
+    from pyvista.themes import _ALLOWED_THEMES, set_plot_theme
+
+    if 'PYVISTA_PLOT_THEME' in os.environ:
+        try:
+            theme = os.environ['PYVISTA_PLOT_THEME']
+            set_plot_theme(theme.lower())
+        except KeyError:
+            allowed = ', '.join([item.name for item in _ALLOWED_THEMES])
+            warnings.warn(
+                f'\n\nInvalid PYVISTA_PLOT_THEME environment variable "{theme}". '
+                f'Should be one of the following: {allowed}'
+            )
+
+
 def raise_has_duplicates(arr):
     """Raise a ValueError if an array is not unique."""
     if has_duplicates(arr):

requirements_docs.txt

@@ -7,7 +7,7 @@ ipygany==0.5.0
 ipyvtklink==0.2.2
 jupyter_sphinx==0.4.0
 jupyterlab==3.4.3
-lxml==4.9.0
+lxml==4.9.1
 matplotlib==3.5.2
 meshio==5.3.4
 mypy-extensions==0.4.3
@@ -27,6 +27,6 @@ sphinx-gallery==0.10.1
 sphinx-notfound-page==0.8
 sphinx-panels==0.6.0
 sphinxcontrib-websupport==1.2.4
-trimesh==3.12.6
+trimesh==3.12.7
 typed-ast==1.5.4
-typing_extensions==4.2.0
+typing_extensions==4.3.0

requirements_test.txt

@@ -5,7 +5,7 @@ Sphinx<4.6.0
 cmocean<2.1
 codecov<2.2.0
 colorcet<3.1.0
-hypothesis<6.48.2
+hypothesis<6.49.2
 imageio-ffmpeg<0.5.0
 imageio<2.20.0
 ipygany<0.6.0

setup.py

@@ -58,6 +58,9 @@
     url='https://github.com/pyvista/pyvista',
     keywords='vtk numpy plotting mesh',
     package_data={
+        'pyvista': [
+            'py.typed',
+        ],
         'pyvista.examples': [
             'airplane.ply',
             'ant.ply',
@@ -84,4 +87,5 @@
         'io': ['meshio>=5.2'],
         'jupyter': ['ipyvtklink', 'pythreejs'],
     },
+    zip_safe=False,
 )