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
@@ -39,7 +39,7 @@ def _get_examples_dir() -> Path:
     FileNotFoundError
         If the examples directory cannot be located in the installation.
     """
-    with get_package_dir() as pkgdir:
+    with get_package_dir(root_path) as pkgdir:
         pkg = Path(pkgdir).resolve()
         for c in (
             pkg / "docs" / "examples",
@@ -72,6 +72,74 @@ def map_pack_to_examples() -> dict[str, List[str]]:
     return examples_by_pack
 
 
+def copy_examples(
+    examples: str | List[str],
+    target_dir: Optional[Path] = None,
+) -> List[Path]:
+    """Copy one or more examples to a target directory.
+
+    Parameters
+    ----------
+    examples : str or list of str
+        Example name(s): 'example1' or ['example1', 'example2']
+    target_dir : Path, optional
+        Target directory where examples should be copied.
+        Defaults to current working directory if not specified.
+    overwrite : bool, default False
+        If True, overwrite existing directories. If False, raise
+        FileExistsError when destination exists.
+
+    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 copy_packs(
+    packs: str | List[str],
+    target_dir: Optional[Path] = None,
+) -> List[Path]:
+    """Copy all examples from one or more packs to a target directory.
+
+    Parameters
+    ----------
+    packs : str or list of str
+        Pack name(s). Can be:
+        - Single pack name: 'pack1'
+        - List of pack names: ['pack1', 'pack2']
+        - Special keyword: 'all' (copies all packs)
+    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 (all examples from the pack(s)).
+
+    Raises
+    ------
+    ValueError
+        If pack name is invalid.
+    FileNotFoundError
+        If pack does not exist.
+    FileExistsError
+        If any destination exists.
+    """
+    return
+
+
 def copy_example(pack_example: str) -> Path:
     """Copy an example into the current working directory.
 

src/diffpy/cmi/packsmanager.py

@@ -68,6 +68,15 @@ def available_packs(self) -> List[str]:
             p.stem for p in self.packs_dir.glob("*.txt") if p.is_file()
         )
 
+    def available_examples(self):
+        """Finds all examples for each pack and builds a dict."""
+        return
+
+    def print_info(self):
+        """Pretty print available and installed packs and examples to
+        console."""
+        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,41 @@
+import pytest
+
+from diffpy.cmi.packsmanager import PacksManager
+
+
+@pytest.mark.parametrize(
+    "expected_dict",
+    [
+        {
+            "pdf": [
+                "ch03NiModelling",
+                "ch06RefineCrystalStructureGen",
+                "ch07StructuralPhaseTransition",
+                "ch08NPRefinement",
+            ]
+        }
+    ],
+)
+def test_available_examples(expected_dict):
+    """Test that available_examples returns a dict."""
+    pkmg = PacksManager()
+    returned_dict = pkmg.available_examples()
+    expected_pack = list(expected_dict.keys())
+    returned_pack = list(returned_dict.keys())
+    for pack in expected_pack:
+        assert pack in returned_pack, f"{pack} not found in returned packs."
+        expected_examples = expected_dict[pack]
+        returned_examples = returned_dict.get(pack, [])
+        for ex in expected_examples:
+            assert (
+                ex in returned_examples
+            ), f"{ex} not found under pack {pack}."
+
+
+def test_print_info(capsys):
+    """Test that print_info prints expected information to stdout."""
+    pkmg = PacksManager()
+    pkmg.print_info()
+    captured = capsys.readouterr()
+    output = captured.out.strip()
+    assert "Available packs" in output or "Installed packs" in output