Improve dimensions show UX command for samples

The 5000 sample test case clearly showed that this needed improvement.
This adds options to control the output by count, by saving to file,
and by printing to stdout.
--sample-names-limit (int; default: 20)
--sample-names-output <path/to/output>
--sample-names-stdout

Author: brinkdp

packages/divbase-cli/src/divbase_cli/cli_commands/dimensions_cli.py

@@ -1,4 +1,5 @@
 import logging
+from pathlib import Path
 
 import typer
 import yaml
@@ -60,6 +61,23 @@ def show_dimensions_index(
             help="If set, will show all unique sample names found across all the VCF files in the project.",
         )
     ),
+    sample_names_limit: int = typer.Option(
+        20,
+        "--sample-names-limit",
+        min=1,
+        help="Maximum number of sample names to display per list in terminal output.",
+    ),
+    sample_names_output: str | None = typer.Option(
+        None,
+        "--sample-names-output",
+        help="Write full sample names to file instead of truncating in terminal output. "
+        "Mutually exclusive with --sample-names-stdout.",
+    ),
+    sample_names_stdout: bool = typer.Option(
+        False,
+        "--sample-names-stdout",
+        help="Print full sample names to stdout (useful for piping). Mutually exclusive with --sample-names-output.",
+    ),
     project: str | None = PROJECT_NAME_OPTION,
 ) -> None:
     """
@@ -69,6 +87,10 @@ def show_dimensions_index(
 
     project_config = resolve_project(project_name=project)
 
+    # These two options are mutually exclusive. But due to how typer handles options, this error will only be raise if --sample-names-output has an input value (i.e. path). If the path is missing, it will raise an error about the missing path argument instead...
+    if sample_names_output and sample_names_stdout:
+        raise typer.BadParameter("Use only one of --sample-names-output or --sample-names-stdout.")
+
     if unique_samples:
         response = make_authenticated_request(
             method="GET",
@@ -77,6 +99,25 @@ def show_dimensions_index(
         )
         unique_sample_names_sorted = DimensionsSamplesResult(**response.json()).unique_samples
         sample_count = len(unique_sample_names_sorted)
+
+        if sample_names_output:
+            output_path = Path(sample_names_output)
+            output_path.write_text("\n".join(unique_sample_names_sorted) + "\n")
+            print(f"Wrote {sample_count} unique sample names to: {output_path}")
+            return
+
+        if sample_names_stdout:
+            print("\n".join(unique_sample_names_sorted))
+            return
+
+        if sample_count > sample_names_limit:
+            preview = unique_sample_names_sorted[:sample_names_limit]
+            print(
+                f"Unique sample names found across all the VCF files in the project (count: {sample_count}, showing first {sample_names_limit}):\n{preview}\n"
+                f"To view all, use --sample-names-output <FILE> or --sample-names-stdout."
+            )
+            return
+
         print(
             f"Unique sample names found across all the VCF files in the project (count: {sample_count}):\n{unique_sample_names_sorted}"
         )
@@ -111,6 +152,15 @@ def show_dimensions_index(
                 record = entry
                 break
         if record:
+            if sample_names_output or sample_names_stdout:
+                _write_or_print_sample_names(
+                    indexed_files=[record],
+                    sample_names_output=sample_names_output,
+                    sample_names_stdout=sample_names_stdout,
+                )
+                return
+
+            _truncate_sample_names_in_entry(record, sample_names_limit)
             print(yaml.safe_dump(record, sort_keys=False))
         else:
             print(
@@ -119,6 +169,17 @@ def show_dimensions_index(
             )
         return
 
+    if sample_names_output or sample_names_stdout:
+        _write_or_print_sample_names(
+            indexed_files=dimensions_info.get("indexed_files", []),
+            sample_names_output=sample_names_output,
+            sample_names_stdout=sample_names_stdout,
+        )
+        return
+
+    for entry in dimensions_info.get("indexed_files", []):
+        _truncate_sample_names_in_entry(entry, sample_names_limit)
+
     print(yaml.safe_dump(dimensions_info, sort_keys=False))
 
 
@@ -163,3 +224,43 @@ def sort_scaffolds(scaffolds: list[str]) -> list[str]:
         "indexed_files": dimensions_list,
         "skipped_files": skipped_list,
     }
+
+
+def _truncate_sample_names_in_entry(entry: dict, sample_names_limit: int) -> None:
+    """
+    Truncate sample names output in terminal, while preserving full counts.
+    """
+    dimensions = entry.get("dimensions", {})
+    sample_names = dimensions.get("sample_names", [])
+    if len(sample_names) > sample_names_limit:
+        dimensions["sample_names"] = sample_names[:sample_names_limit]
+        dimensions["sample_names_note"] = (
+            f"Showing first {sample_names_limit} of {len(sample_names)} samples. "
+            "Use --sample-names-output <FILE> or --sample-names-stdout to view all."
+        )
+
+
+def _write_or_print_sample_names(
+    indexed_files: list[dict],
+    sample_names_output: str | None,
+    sample_names_stdout: bool,
+) -> None:
+    """
+    Export full sample names data from divbase-cli dimensions show
+    either to a file or to stdout. If used without --unique-samples, it will also include the filename that each sample occurs in.
+    """
+    lines: list[str] = []
+    for entry in indexed_files:
+        file_name = entry.get("filename", "")
+        sample_names = entry.get("dimensions", {}).get("sample_names", [])
+        for sample_name in sample_names:
+            lines.append(f"{file_name}\t{sample_name}")
+
+    if sample_names_output:
+        output_path = Path(sample_names_output)
+        output_path.write_text("\n".join(lines) + ("\n" if lines else ""))
+        print(f"Wrote {len(lines)} sample-name rows to: {output_path}")
+        return
+
+    if sample_names_stdout:
+        print("\n".join(lines))

tests/e2e_integration/cli_commands/test_dimensions_cli.py

@@ -365,3 +365,117 @@ def test_show_unique_scaffolds_dedicated_endpoint(
     # Verify numeric scaffolds come first, sorted numerically
     numeric_scaffolds = [s for s in scaffold_names if s.isdigit()]
     assert numeric_scaffolds == sorted(numeric_scaffolds, key=int), "Numeric scaffolds should be sorted numerically"
+
+
+def test_show_dimensions_sample_names_output_writes_file(
+    CONSTANTS,
+    run_update_dimensions,
+    project_map,
+    logged_in_edit_user_with_existing_config,
+    tmp_path,
+):
+    """
+    Test that --sample-names-output writes full sample-name rows to file.
+    """
+    project_name = CONSTANTS["SPLIT_SCAFFOLD_PROJECT"]
+    bucket_name = CONSTANTS["PROJECT_TO_BUCKET_MAP"][project_name]
+    project_id = project_map[project_name]
+    user_id = 1
+
+    run_update_dimensions(bucket_name=bucket_name, project_id=project_id, project_name=project_name, user_id=user_id)
+
+    output_path = tmp_path / "sample_names.tsv"
+    command = f"dimensions show --project {project_name} --sample-names-output {output_path}"
+    cli_result = runner.invoke(app, command)
+    assert cli_result.exit_code == 0, f"Command failed with: {cli_result.stdout}"
+    assert output_path.exists(), f"Expected output file {output_path} to exist"
+
+    rows = output_path.read_text().strip().splitlines()
+    assert len(rows) > 0, "Expected at least one sample row in output file"
+    assert all("\t" in row for row in rows), "Expected tab-delimited rows in format: filename<TAB>sample_name"
+    assert any("HOM_20ind_17SNPs" in row for row in rows), "Expected known VCF filename in output rows"
+    assert "Wrote" in cli_result.stdout and "sample-name rows" in cli_result.stdout
+
+
+def test_show_dimensions_sample_names_stdout_streams_rows(
+    CONSTANTS,
+    run_update_dimensions,
+    project_map,
+    logged_in_edit_user_with_existing_config,
+):
+    """
+    Test that --sample-names-stdout prints filename/sample rows to stdout.
+    """
+    project_name = CONSTANTS["SPLIT_SCAFFOLD_PROJECT"]
+    bucket_name = CONSTANTS["PROJECT_TO_BUCKET_MAP"][project_name]
+    project_id = project_map[project_name]
+    user_id = 1
+
+    run_update_dimensions(bucket_name=bucket_name, project_id=project_id, project_name=project_name, user_id=user_id)
+
+    command = f"dimensions show --project {project_name} --sample-names-stdout"
+    cli_result = runner.invoke(app, command)
+    assert cli_result.exit_code == 0, f"Command failed with: {cli_result.stdout}"
+
+    lines = [line for line in cli_result.stdout.splitlines() if line.strip()]
+    assert len(lines) > 0, "Expected streamed rows in stdout"
+    assert all("\t" in line for line in lines), "Expected tab-delimited rows in format: filename<TAB>sample_name"
+
+
+def test_show_dimensions_truncates_sample_names_in_terminal(
+    CONSTANTS,
+    run_update_dimensions,
+    project_map,
+    logged_in_edit_user_with_existing_config,
+):
+    """
+    Test that --sample-names-limit truncates shown sample names and adds a note.
+    """
+    project_name = CONSTANTS["SPLIT_SCAFFOLD_PROJECT"]
+    bucket_name = CONSTANTS["PROJECT_TO_BUCKET_MAP"][project_name]
+    project_id = project_map[project_name]
+    user_id = 1
+
+    run_update_dimensions(bucket_name=bucket_name, project_id=project_id, project_name=project_name, user_id=user_id)
+
+    command = f"dimensions show --project {project_name} --sample-names-limit 2"
+    cli_result = runner.invoke(app, command)
+    assert cli_result.exit_code == 0, f"Command failed with: {cli_result.stdout}"
+
+    dimensions_info = yaml.safe_load(cli_result.stdout)
+    indexed_files = dimensions_info.get("indexed_files", [])
+    assert len(indexed_files) > 0, "Expected indexed files in output"
+
+    first_entry_dimensions = indexed_files[0].get("dimensions", {})
+    shown_sample_names = first_entry_dimensions.get("sample_names", [])
+    assert len(shown_sample_names) <= 2, f"Expected sample_names to be truncated to <=2, got {shown_sample_names}"
+    assert "sample_names_note" in first_entry_dimensions, "Expected truncation note in output"
+
+
+def test_show_dimensions_rejects_output_and_stdout_together(
+    CONSTANTS,
+    run_update_dimensions,
+    project_map,
+    logged_in_edit_user_with_existing_config,
+    tmp_path,
+):
+    """
+    Test that using --sample-names-output and --sample-names-stdout together fails.
+    """
+    project_name = CONSTANTS["SPLIT_SCAFFOLD_PROJECT"]
+    bucket_name = CONSTANTS["PROJECT_TO_BUCKET_MAP"][project_name]
+    project_id = project_map[project_name]
+    user_id = 1
+
+    run_update_dimensions(bucket_name=bucket_name, project_id=project_id, project_name=project_name, user_id=user_id)
+
+    output_path = tmp_path / "sample_names.tsv"
+    command = f"dimensions show --project {project_name} --sample-names-output {output_path} --sample-names-stdout"
+    cli_result = runner.invoke(app, command)
+    assert cli_result.exit_code != 0, "Expected command to fail when both output modes are provided"
+    combined_output = (
+        (cli_result.stdout or "")
+        + (getattr(cli_result, "stderr", "") or "")
+        + (str(cli_result.exception) if cli_result.exception else "")
+    )
+    assert "Use only one of --sample-names-output or --sample-names-stdout." in combined_output