feat: Build dict for copy examples command

news/dict-build-test.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Add test for building examples dict.
+
+**Changed:**
+
+* Change example dict build process.
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/cmi/__init__.py

@@ -18,8 +18,23 @@
 from importlib.resources import as_file, files
 
 
-def get_package_dir():
-    resource = files(__name__)
+def get_package_dir(root_path=None):
+    """Get the package directory as a context manager.
+
+    Parameters
+    ----------
+    root_path : str, optional
+        Used for testing, overrides the files(__name__) call.
+
+    Returns
+    -------
+    context manager
+        A context manager that yields a pathlib.Path to the package directory.
+    """
+    if root_path is None:
+        resource = files(__name__)
+    else:
+        resource = root_path
     return as_file(resource)
 
 

src/diffpy/cmi/packsmanager.py

@@ -28,9 +28,9 @@
 __all__ = ["PacksManager"]
 
 
-def _installed_packs_dir() -> Path:
+def _installed_packs_dir(root_path=None) -> Path:
     """Locate requirements/packs/ for the installed package."""
-    with get_package_dir() as pkgdir:
+    with get_package_dir(root_path) as pkgdir:
         pkg = Path(pkgdir).resolve()
         for c in (
             pkg / "requirements" / "packs",
@@ -51,10 +51,24 @@ class PacksManager:
     packs_dir : pathlib.Path
         Absolute path to the installed packs directory.
         Defaults to `requirements/packs` under the installed package.
+    examples_dir : pathlib.Path
+        Absolute path to the installed examples directory.
+        Defaults to `docs/examples` under the installed package.
     """
 
-    def __init__(self) -> None:
-        self.packs_dir = _installed_packs_dir()
+    def __init__(self, root_path=None) -> None:
+        self.packs_dir = _installed_packs_dir(root_path)
+        self.examples_dir = self._get_examples_dir()
+
+    def _get_examples_dir(self) -> Path:
+        """Return the absolute path to the installed examples directory.
+
+        Returns
+        -------
+        pathlib.Path
+            Directory containing shipped examples.
+        """
+        return (self.packs_dir / ".." / ".." / "docs" / "examples").resolve()
 
     def available_packs(self) -> List[str]:
         """List all available packs.
@@ -68,6 +82,37 @@ def available_packs(self) -> List[str]:
             p.stem for p in self.packs_dir.glob("*.txt") if p.is_file()
         )
 
+    def available_examples(self) -> dict[str, List[tuple[str, Path]]]:
+        """Finds all examples for each pack and builds a dict.
+
+        Parameters
+        ----------
+        root_path : Path
+            Root path to the examples directory.
+        Returns
+        -------
+        dict
+            A dictionary mapping pack names to lists of example names.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the provided root_path does not exist or is not a directory.
+        """
+        example_dir = self.examples_dir
+        examples_dict = {}
+        for pack_path in sorted(example_dir.iterdir()):
+            if pack_path.is_dir():
+                pack_name = pack_path.stem
+                examples_dict[pack_name] = []
+                for example_path in sorted(pack_path.iterdir()):
+                    if example_path.is_dir():
+                        example_name = example_path.stem
+                        examples_dict[pack_name].append(
+                            (example_name, example_path)
+                        )
+        return examples_dict
+
     def _resolve_pack_file(self, identifier: Union[str, Path]) -> Path:
         """Resolve a pack identifier to an absolute .txt path.
 

tests/test_packsmanager.py

@@ -0,0 +1,94 @@
+import pytest
+
+from diffpy.cmi.packsmanager import PacksManager
+
+
+def paths_and_names_match(expected, actual, root):
+    """Compare two tuples (example_name, path), ignoring temp dir
+    differences."""
+    if len(expected) != len(actual):
+        return False
+    for (exp_name, exp_path), (act_name, act_path) in zip(expected, actual):
+        if exp_name != act_name:
+            return False
+        actual_rel_path = str(act_path.relative_to(root))
+        if actual_rel_path != exp_path:
+            return False
+    return True
+
+
+example_params = [
+    # 1) pack with no examples.  Expect {'empty_pack': []}
+    # 2) pack with multiple examples.
+    #  Expect {'full_pack': [('example1`, path_to_1'), 'example2', path_to_2)]
+    # 3) multiple packs.  Expect dict with multiple pack:tuple pairs
+    # 4) no pack found. Expect {}
+    # case 1: pack with no examples.  Expect {'empty_pack': []}
+    # 5) multiple packs with the same example names
+    # Expect dict with multiple pack:tuple pairs
+    (
+        "case1",
+        {"empty_pack": []},
+    ),
+    # case 2: pack with multiple examples.
+    # Expect {'full_pack': [('example1', path_to_1),
+    #           ('example2', path_to_2)]}
+    (
+        "case2",
+        {
+            "full_pack": [
+                ("ex1", "case2/docs/examples/full_pack/ex1"),
+                ("ex2", "case2/docs/examples/full_pack/ex2"),
+            ]
+        },
+    ),
+    # case 3: multiple packs.  Expect dict with multiple pack:tuple pairs
+    (
+        "case3",
+        {
+            "packA": [
+                ("ex1", "case3/docs/examples/packA/ex1"),
+                ("ex2", "case3/docs/examples/packA/ex2"),
+            ],
+            "packB": [("ex3", "case3/docs/examples/packB/ex3")],
+        },
+    ),
+    (  # case 4: no pack found. Expect {}
+        "case4",
+        {},
+    ),
+    (  # case 5: multiple packs with duplicate example names
+        # Expect dict with multiple pack:tuple pairs
+        "case5",
+        {
+            "packA": [
+                ("ex1", "case5/docs/examples/packA/ex1"),
+            ],
+            "packB": [
+                ("ex1", "case5/docs/examples/packB/ex1"),
+            ],
+        },
+    ),
+]
+
+
+@pytest.mark.parametrize("input,expected", example_params)
+def test_available_examples(input, expected, example_cases):
+    case_dir = example_cases / input
+    pkmg = PacksManager(case_dir)
+    actual = pkmg.available_examples()
+    assert actual.keys() == expected.keys()
+    for pack in expected:
+        assert paths_and_names_match(
+            expected[pack], actual[pack], example_cases
+        )
+
+
+@pytest.mark.parametrize("input,expected", example_params)
+def test_tmp_file_structure(input, expected, example_cases):
+    example_path = example_cases / input
+    for path in example_path.rglob("*"):
+        if path.suffix:
+            assert path.is_file()
+        else:
+            assert path.is_dir()