feat: build examples dict for cli commands

src/diffpy/cmi/__init__.py

@@ -18,7 +18,19 @@
 from importlib.resources import as_file, files
 
 
-def get_package_dir():
+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.
+    """
     resource = files(__name__)
     return as_file(resource)
 

src/diffpy/cmi/cli.py

@@ -26,7 +26,7 @@
 
 
 # Examples
-def _get_examples_dir() -> Path:
+def _get_examples_dir(root_path=None) -> Path:
     """Return the absolute path to the installed examples directory.
 
     Returns
@@ -72,6 +72,43 @@ def map_pack_to_examples() -> dict[str, List[str]]:
     return examples_by_pack
 
 
+def copy_examples(
+    examples: List[str],
+    target_dir: Optional[Path] = None,
+) -> List[Path]:
+    """Copy one or more examples to a target directory.
+
+    Parameters
+    ----------
+    examples : list of str
+        Example name(s): ['example1'], ['pack1']
+    target_dir : Path, optional
+        Target directory where examples should be copied.
+        Defaults to current working directory if not specified.
+
+    Returns
+    -------
+    list of Path
+        List of destination paths created.
+
+    Raises
+    ------
+    ValueError
+        If example name is ambiguous (exists in multiple packs).
+    FileNotFoundError
+        If example does not exist.
+    FileExistsError
+        If destination exists and overwrite=False.
+    """
+    return
+
+
+def print_info(pack_examples_dict):
+    """Pretty print available and installed packs and examples to
+    console."""
+    return
+
+
 def copy_example(pack_example: str) -> Path:
     """Copy an example into the current working directory.
 

src/diffpy/cmi/packsmanager.py

@@ -68,6 +68,25 @@ def available_packs(self) -> List[str]:
             p.stem for p in self.packs_dir.glob("*.txt") if p.is_file()
         )
 
+    def available_examples(self, root_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.
+        """
+        return
+
     def _resolve_pack_file(self, identifier: Union[str, Path]) -> Path:
         """Resolve a pack identifier to an absolute .txt path.
 

tests/test__init__.py

@@ -0,0 +1,11 @@
+# from diffpy.cmi import get_package_dir
+from pathlib import Path
+
+import pytest
+
+
+@pytest.mark.parametrize("root_path", [None, str(Path(__file__).parent)])
+def test_get_package_dir(root_path):
+    """Test that get_package_dir returns a valid path context
+    manager."""
+    assert False

tests/test_packsmanager.py

@@ -0,0 +1,47 @@
+import pytest
+
+from diffpy.cmi.packsmanager import PacksManager
+
+
+@pytest.mark.parametrize(
+    "expected",
+    [
+        {
+            # test with pack that has examples
+            "pack1": [
+                "ex1",
+                "ex2",
+                "ex3",
+            ]
+        },
+        {
+            # test pack with no examples
+            "no_examples": []
+        },
+    ],
+)
+def test_available_examples(temp_path, expected):
+    for pack, examples in expected.items():
+        pack_dir = temp_path / pack
+        pack_dir.mkdir(parents=True, exist_ok=True)
+        for ex in examples:
+            ex_dir = pack_dir / ex
+            ex_dir.mkdir(parents=True, exist_ok=True)
+    pkmg = PacksManager(temp_path)
+    actual = pkmg.available_examples(temp_path)
+    assert actual == expected
+
+
+def test_available_examples_bad(temp_path):
+    pkmg = PacksManager(temp_path)
+    bad_path = temp_path / "nonexistent"
+    with pytest.raises(FileNotFoundError):
+        pkmg.available_examples(bad_path)
+
+
+def test_print_info(temp_path, capsys):
+    pkmg = PacksManager(temp_path)
+    pkmg.print_info()
+    captured = capsys.readouterr()
+    output = captured.out.strip()
+    assert "Available packs" in output or "Installed packs" in output