viralunity 1.2.0__py3-none-any.whl

viralunity/__init__.py

@@ -0,0 +1,4 @@
+__program__ = "viralunity"
+_description = "A pipeline for viral metagenomics analysis."
+
+__version__ = "1.2.0"

viralunity/_orchestrator.py

@@ -0,0 +1,135 @@
+"""Shared pipeline-orchestration helpers used by ``viralunity_consensus`` and
+``viralunity_meta``.
+
+Each pipeline still owns its own ``validate_args``, ``generate_config_file``,
+``run_snakemake_workflow``, and ``main`` so that existing test patches at
+those module-level names continue to work; the helpers in this module are
+called from inside those functions to remove what would otherwise be
+duplicated boilerplate.
+"""
+
+import logging
+import os
+from typing import Any, Callable, Dict, Optional
+
+from snakemake import snakemake
+
+from viralunity.config_generator import ConfigGenerator
+from viralunity.exceptions import ValidationError, ViralUnityError
+from viralunity.provenance import write_run_manifest
+
+logger = logging.getLogger(__name__)
+
+
+def start_config(args: Dict[str, Any], samples: Dict[str, list]) -> ConfigGenerator:
+    """Instantiate a ``ConfigGenerator`` and add the keys both pipelines
+    always set: samples, output, threads.
+
+    The caller is responsible for adding pipeline-specific keys (consensus
+    or metagenomics settings), per-rule resource settings, and calling
+    ``generator.save()``.
+    """
+    logger.info("Generating configuration file")
+    generator = ConfigGenerator(args["config_file"])
+    generator.add_samples(samples, args["data_type"])
+    generator.add_output(args["output"], args["run_name"])
+    generator.add_threads(args["threads"])
+    return generator
+
+
+def run_workflow(workflow_path: str, args: Dict[str, Any]) -> bool:
+    """Run a Snakemake workflow with the kwargs both pipelines share.
+
+    Args:
+        workflow_path: Absolute path to the ``.smk`` file to execute.
+        args: Pipeline argument dict. Must contain ``config_file`` and
+            ``threads_total``.
+
+    Raises:
+        ValidationError: If ``workflow_path`` does not exist.
+    """
+    logger.info("Starting Snakemake workflow")
+
+    if not os.path.isfile(workflow_path):
+        raise ValidationError(f"Workflow file not found: {workflow_path}")
+
+    successful = snakemake(
+        workflow_path,
+        configfiles=[args["config_file"]],
+        cores=args["threads_total"],
+        use_conda=True,
+        conda_prefix=args.get("conda_prefix"),
+        targets=["all"],
+    )
+
+    if successful:
+        logger.info("Snakemake workflow completed successfully")
+    else:
+        logger.error("Snakemake workflow failed")
+
+    return successful
+
+
+def run_pipeline(
+    args: Dict[str, Any],
+    *,
+    resolve_paths: Callable[[Dict[str, Any]], None],
+    validate: Callable[[Dict[str, Any]], Optional[Dict[str, list]]],
+    generate_config: Callable[[Dict[str, list], Dict[str, Any]], None],
+    run_workflow_fn: Callable[[Dict[str, Any]], bool],
+    skip_when_no_samples: bool = False,
+) -> int:
+    """The try/except ``main`` skeleton shared by both pipelines.
+
+    Args:
+        args: Pipeline argument dict.
+        resolve_paths: Called first to convert relative path args to
+            absolute paths.
+        validate: Called to validate args and return the samples dict.
+        generate_config: Called to write the Snakemake config file.
+        run_workflow_fn: Called to execute the Snakemake workflow. The
+            pipeline-specific module passes its own
+            ``run_snakemake_workflow`` so test patches at that name
+            keep working.
+        skip_when_no_samples: If ``True``, return 0 (success) when the
+            validated samples dict is empty. ``viralunity_meta`` opts in;
+            ``viralunity_consensus`` does not.
+
+    Returns:
+        Exit code (0 for success, 1 for failure).
+    """
+    try:
+        resolve_paths(args)
+        samples = validate(args)
+
+        if skip_when_no_samples and (samples is None or len(samples) == 0):
+            logger.warning("No samples were provided.")
+            return 0
+
+        generate_config(samples, args)
+
+        if args.get("create_config_only", False):
+            logger.info("Config file created. Exiting without running workflow.")
+            return 0
+
+        # Provenance: record version, config, and input checksums for the run.
+        # Best-effort — a manifest failure must never abort an analysis.
+        try:
+            manifest_path = write_run_manifest(args, samples)
+            logger.info(f"Wrote run manifest: {manifest_path}")
+        except Exception as e:
+            logger.warning(f"Could not write run manifest: {e}")
+
+        successful = run_workflow_fn(args)
+        return 0 if successful else 1
+
+    except ViralUnityError as e:
+        # Expected, user-facing failures (bad inputs, missing files/DBs, config
+        # errors). Log a clean message with the machine-readable error code so a
+        # caller/service can key off it; no stack trace for these.
+        logger.error(f"[{e.code}] {e}")
+        return 1
+    except Exception as e:
+        # Genuinely unexpected: keep the traceback for debugging.
+        logger.exception(f"Unexpected error: {e}")
+        return 1

viralunity/_subprocess.py

@@ -0,0 +1,52 @@
+"""Shared subprocess helper for ViralUnity CLI commands.
+
+Internal module — not part of the public API. Used by the `get-databases`
+and `build-deacon-index` subcommands to invoke external tools (`wget`,
+`tar`, `diamond`, `deacon`, `datasets`, ...) with consistent echoing and
+error handling.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Optional, Sequence
+
+import click
+
+#: Default wall-clock ceiling for a single external command (seconds). Long
+#: enough for large downloads/DB builds, but bounded so a hung tool cannot block
+#: a run (or a service worker) indefinitely. Override per-call via ``timeout``.
+DEFAULT_TIMEOUT = 6 * 60 * 60  # 6 hours
+
+
+def run_command(
+    cmd: Sequence[object],
+    cwd: Optional[str] = None,
+    timeout: Optional[float] = DEFAULT_TIMEOUT,
+) -> None:
+    """Run a subprocess command, streaming output and raising on failure.
+
+    Args:
+        cmd: Argument list (no shell). Each element is coerced to ``str``
+            when echoed; pass paths and flags as separate elements.
+        cwd: Optional working directory in which to run the command.
+        timeout: Wall-clock ceiling in seconds. Defaults to
+            ``DEFAULT_TIMEOUT``; pass ``None`` to disable.
+
+    Raises:
+        click.ClickException: If the subprocess exits non-zero or times out.
+            The exit code/timeout and command are included in the message so
+            the failure surfaces cleanly in the CLI output.
+    """
+    click.echo(f"$ {' '.join(str(c) for c in cmd)}")
+    try:
+        result = subprocess.run(list(cmd), cwd=cwd, timeout=timeout)
+    except subprocess.TimeoutExpired as e:
+        raise click.ClickException(
+            f"Command timed out after {e.timeout:.0f}s: " f"{' '.join(str(c) for c in cmd)}"
+        ) from e
+    if result.returncode != 0:
+        raise click.ClickException(
+            f"Command failed with exit code {result.returncode}: "
+            f"{' '.join(str(c) for c in cmd)}"
+        )