Add get_petsc_dirs utility function

Author: connorjward

petsctools/__init__.py

@@ -3,6 +3,7 @@
     get_config,
     get_petsc_dir,
     get_petsc_arch,
+    get_petsc_dirs,
     get_petscvariables,
     get_petscconf_h,
     get_external_packages,

petsctools/config.py

@@ -36,6 +36,47 @@ def get_petsc_arch():
     return get_config()["PETSC_ARCH"]
 
 
+def get_petsc_dirs(
+    *,
+    prefix: str = "",
+    subdir: str | None = None,
+) -> tuple[str, str]:
+    """Return $PETSC_DIR and $PETSC_DIR/$PETSC_ARCH.
+
+    This function is useful for generating compiler arguments. For example
+
+    .. code-block:: python
+
+        get_petsc_dirs(subdir="include", prefix="-I")
+
+    will return
+
+    .. code-block:: python
+
+        ("-I/path/to/petsc/include", "-I/path/to/petsc/mypetscarch/include")
+
+    Parameters
+    ----------
+    prefix :
+        Optional prefix to prepend to the paths.
+    subdir :
+        Optional subdirectory to include in the returned paths.
+
+    Returns
+    -------
+    tuple :
+        ``$PETSC_DIR`` and ``$PETSC_DIR/$PETSC_ARCH`` with appropriate
+        sub-directories and prefixes.
+
+    """
+    dirs = []
+    for path in [[get_petsc_dir()], [get_petsc_dir(), get_petsc_arch()]]:
+        if subdir:
+            path.append(subdir)
+        dirs.append(f"{prefix}{os.path.join(*path)}")
+    return tuple(dirs)
+
+
 @functools.lru_cache()
 def get_petscvariables():
     """Return PETSc's configuration information."""

tests/test_config.py

@@ -20,6 +20,21 @@ def test_get_config():
     )
 
 
+def test_get_petsc_dirs():
+    petsc_dir = petsctools.get_petsc_dir()
+    petsc_arch = petsctools.get_petsc_arch()
+
+    expected = (petsc_dir, f"{petsc_dir}/{petsc_arch}") 
+    assert petsctools.get_petsc_dirs() == expected
+
+    expected = (
+        f"PREFIX{petsc_dir}/SUBDIR", f"PREFIX{petsc_dir}/{petsc_arch}/SUBDIR"
+    )
+    assert (
+        petsctools.get_petsc_dirs(prefix="PREFIX", subdir="SUBDIR") == expected
+    )
+
+
 def test_get_petscvariables():
     petsctools.get_petscvariables()