divbase-cli 0.1.0a1__py3-none-any.whl

divbase_cli/cli_commands/query_cli.py

@@ -0,0 +1,300 @@
+"""
+Query subcommand for the DivBase CLI.
+
+Submits queries (sample metadata and/or bcftools) to the DivBase API.
+
+If sample metadata query:
+    results are printed to the console.
+
+If bcftools query:
+    a task id is returned which can be used to check the status of the job.
+    After task completed, a merged VCF file will be added to the project's storage bucket which can be downloaded by the user.
+
+
+TODO:
+- Ability to download results file given task id with the file cli?
+-
+"""
+
+import logging
+from pathlib import Path
+
+import typer
+from rich import print
+
+from divbase_cli.cli_commands.shared_args_options import PROJECT_NAME_OPTION
+from divbase_cli.cli_config import cli_settings
+from divbase_cli.config_resolver import ensure_logged_in, resolve_project
+from divbase_cli.user_auth import make_authenticated_request
+from divbase_lib.api_schemas.queries import (
+    BcftoolsQueryRequest,
+    SampleMetadataQueryRequest,
+    SampleMetadataQueryTaskResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+METADATA_TSV_ARGUMENT = typer.Option(
+    cli_settings.METADATA_TSV_NAME, help="Name of the sample metadata TSV file in the project's data store on DivBase."
+)
+
+BCFTOOLS_ARGUMENT = typer.Option(
+    ...,
+    help="""
+        String consisting of the bcftools view command(s) to run. E.g. "view -r 21:15000000-25000000" or "view -s".
+        The string cannot be empty; if you only want to subset on the selected samples, use: --command "view -s"
+        """,
+)
+
+# Sample metadata and VCF queries both use the same core text, so it is defined up here.
+TSV_FILTER_SYNTAX = (
+    "String consisting of keys:values in the tsv file to filter on. "
+    "The syntax is 'Key1:Value1,Value2;Key2:Value3,Value4', where the keys are the column header names in the tsv, "
+    "and values are the column values. Multiple values for a key are separated by commas, and multiple keys are "
+    "separated by semicolons. When multiple keys are provided, an intersect query will be performed. "
+    "E.g. 'Area:West of Ireland,Northern Portugal;Sex:F'."
+)
+
+TSV_FILTER_HELP_TEXT_VCF = (
+    "This option calculates the samples to filter the VCFs on based on a sample metadata query. "
+    + TSV_FILTER_SYNTAX
+    + "\n\nMutually exclusive with --samples, --samples-file, and --all-samples."
+)
+
+SAMPLE_SELECTION_HELP_PANEL = "Sample Selection (Required: Include Exactly One)"
+VCF_QUERY_HELP_TEXT = (
+    "Submit a VCF query to run on the DivBase API. "
+    "A single, merged VCF file with the query results will be added to the project on success.\n\n"
+    "Exactly one sample-selection mode is required: "
+    "--tsv-filter | --samples | --samples-file | --all-samples."
+)
+
+query_app = typer.Typer(
+    help="Run queries on the VCF files stored in the project's data store on DivBase. Queries are run on the DivBase API",
+    no_args_is_help=True,
+)
+
+
+@query_app.command("tsv")
+def sample_metadata_query(
+    tsv_filter: str = typer.Argument(
+        ...,
+        help=TSV_FILTER_SYNTAX,
+    ),
+    show_sample_results: bool = typer.Option(
+        default=False,
+        help="Print sample_ID and Filename results from the query.",
+    ),
+    metadata_tsv_name: str = METADATA_TSV_ARGUMENT,
+    project: str | None = PROJECT_NAME_OPTION,
+) -> None:
+    """
+    Query the tsv sidecar metadata file for the VCF files in the project's data store on DivBase.
+    Returns the sample IDs and filenames that match the query.
+    """
+    project_config = resolve_project(project_name=project)
+    logged_in_url = ensure_logged_in(desired_url=project_config.divbase_url)
+
+    request_data = SampleMetadataQueryRequest(tsv_filter=tsv_filter, metadata_tsv_name=metadata_tsv_name)
+
+    response = make_authenticated_request(
+        method="POST",
+        divbase_base_url=logged_in_url,
+        api_route=f"v1/query/sample-metadata/projects/{project_config.name}",
+        json=request_data.model_dump(),
+        timeout=20,  # This is longer than default (5), as api call response is query result, not a task-id.
+    )
+
+    results = SampleMetadataQueryTaskResult(**response.json())
+
+    if results.warnings:
+        print("[yellow]Warnings:[/yellow]")
+        for warning in results.warnings:
+            print(f"  • {warning}")
+        print()
+
+    if show_sample_results:
+        print("[bright_blue]Name and file for each sample in query results:[/bright_blue]")
+        for sample in results.sample_and_filename_subset:
+            print(f"Sample ID: '{sample.sample_id}', Filename: '{sample.filename}'")
+
+    print(f"The results for the query ([bright_blue]{results.query_message}[/bright_blue]):")
+
+    unique_sample_ids = results.unique_sample_ids or []
+    unique_filenames = results.unique_filenames or []
+    print(f"Unique Sample IDs: {unique_sample_ids}")
+    print(f"Unique filenames: {unique_filenames}\n")
+    if not unique_sample_ids:
+        print("[yellow]No samples match your query filters.[/yellow]\n")
+
+
+@query_app.command("vcf", help=VCF_QUERY_HELP_TEXT)
+def vcf_query(
+    tsv_filter: str | None = typer.Option(
+        None, help=TSV_FILTER_HELP_TEXT_VCF, rich_help_panel=SAMPLE_SELECTION_HELP_PANEL
+    ),
+    samples: str | None = typer.Option(
+        None,
+        help="Comma-separated list of sample IDs. Mutually exclusive with --tsv-filter, --samples-file, and --all-samples.",
+        rich_help_panel=SAMPLE_SELECTION_HELP_PANEL,
+    ),
+    samples_file: Path | None = typer.Option(
+        None,
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        help=(
+            "Path to a UTF-8 text file with one sample ID per line. Blank lines and lines starting with # are ignored. "
+            "Mutually exclusive with --tsv-filter, --samples, and --all-samples."
+        ),
+        rich_help_panel=SAMPLE_SELECTION_HELP_PANEL,
+    ),
+    all_samples: bool = typer.Option(
+        False,
+        "--all-samples",
+        help=(
+            "Use all samples in the project for the query. "
+            "Mutually exclusive with --tsv-filter, --samples, and --samples-file."
+        ),
+        rich_help_panel=SAMPLE_SELECTION_HELP_PANEL,
+    ),
+    command: str = BCFTOOLS_ARGUMENT,
+    metadata_tsv_name: str = METADATA_TSV_ARGUMENT,
+    project: str | None = PROJECT_NAME_OPTION,
+) -> None:
+    """
+    Submit a VCF query to run on the DivBase API. A single, merged VCF file with the query results will be added to the project on success.
+    """
+
+    # TODO Error handling for subprocess calls.
+    # TODO: handle the case empty results are returned from tsv_query()
+    # TODO what if a job fails and the user wants to re-run it? do we store temp files?
+
+    # Note! Pydantic model validator also enforces this on the API side just queries can be submitted directly to the endpoint.
+    # This block here is to catch it on the CLI side with a more user-friendly error message before even making the API call.
+    has_tsv_filter = tsv_filter is not None
+    has_samples = samples is not None
+    has_samples_file = samples_file is not None
+    has_all_samples = all_samples
+    selection_count = sum([has_tsv_filter, has_samples, has_samples_file, has_all_samples])
+    if selection_count > 1:
+        raise typer.BadParameter("Use only one of --tsv-filter, --samples, --samples-file, or --all-samples.")
+    if selection_count == 0:
+        raise typer.BadParameter(
+            "Sample selection is required. Use one of --tsv-filter, --samples, --samples-file, or --all-samples."
+        )
+
+    normalized_samples, sample_input_warnings = _normalize_samples_input(samples=samples, samples_file=samples_file)
+    if sample_input_warnings:
+        print("[yellow]Warnings:[/yellow]")
+        for warning in sample_input_warnings:
+            print(f"  • {warning}")
+        print()
+
+    project_config = resolve_project(project_name=project)
+    logged_in_url = ensure_logged_in(desired_url=project_config.divbase_url)
+
+    request_data = BcftoolsQueryRequest(
+        tsv_filter=tsv_filter,
+        command=command,
+        metadata_tsv_name=metadata_tsv_name,
+        samples=normalized_samples,
+        all_samples=all_samples,
+    )
+
+    response = make_authenticated_request(
+        method="POST",
+        divbase_base_url=logged_in_url,
+        api_route=f"v1/query/vcf/projects/{project_config.name}",
+        json=request_data.model_dump(),
+    )
+
+    task_id = response.json()
+    print(
+        f"Job submitted successfully with task id: {task_id}. To check the status of your job, use the command: divbase-cli task-history id {task_id}"
+    )
+
+
+def _normalize_samples_input(samples: str | None, samples_file: Path | None) -> tuple[list[str] | None, list[str]]:
+    """
+    Normalize sample selection inputs from CLI options.
+    """
+    if samples is not None:
+        normalized = []
+        for sample in samples.split(","):
+            sample_clean = sample.strip()
+            if sample_clean:
+                normalized.append(sample_clean)
+
+        if not normalized:
+            raise typer.BadParameter("--samples must contain at least one non-empty sample ID.")
+        return normalized, []
+
+    if samples_file is not None:
+        raw_lines = samples_file.read_text(encoding="utf-8").splitlines()
+        normalized = []
+        warnings = []
+        delimiter_lines = []
+        found_delimiters = set()
+        disallowed_delimiters = (",", ";", "\t", "|")
+        delimiter_display = {
+            ",": "','",
+            ";": "';'",
+            "\t": "'tab'",
+            "|": "'|'",
+        }
+
+        for line_number, raw_line in enumerate(raw_lines, start=1):
+            stripped = raw_line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+
+            normalized.append(stripped)
+            line_delimiters = set()
+            for delimiter in disallowed_delimiters:
+                if delimiter in stripped:
+                    line_delimiters.add(delimiter)
+
+            if line_delimiters:
+                delimiter_lines.append((line_number, stripped))
+                found_delimiters.update(line_delimiters)
+
+        if not normalized:
+            raise typer.BadParameter(
+                f"Samples file has no sample IDs after ignoring blank/comment lines: {samples_file}. Please ensure that it contains at least one sample ID."
+            )
+
+        if delimiter_lines:
+            preview_entries = []  # Only preview up to the first 3 lines with delimiters to avoid overwhelming the user with a long list if there are many problematic lines.
+            for line_number, line_value in delimiter_lines[:3]:
+                preview_entries.append(f"line {line_number} ('{line_value}')")
+            preview = ", ".join(preview_entries)
+
+            previewed_line_count = min(len(delimiter_lines), 3)
+            extra_line_count = len(delimiter_lines) - previewed_line_count
+            extra_msg = f", +{extra_line_count} more line(s)" if extra_line_count > 0 else ""
+
+            delimiter_names = []
+            for delimiter in disallowed_delimiters:
+                if delimiter in found_delimiters:
+                    delimiter_names.append(delimiter_display[delimiter])
+            delimiters_found_str = ", ".join(delimiter_names)
+
+            raise typer.BadParameter(
+                "Invalid --samples-file format: expected one sample ID per line with no delimiters. "
+                f"Found delimiter(s) {delimiters_found_str} on {len(delimiter_lines)} line(s): \n{preview}{extra_msg}. "
+                "\nPlease do not use delimiters (',' ';' '\\t' '|') in your samples file."
+            )
+
+        if len(normalized) == 1:
+            warnings.append(
+                "Only one sample ID was found in --samples-file after ignoring blank/comment lines. "
+                "If this was not intended, verify that the file has one sample ID per line."
+            )
+
+        return normalized, warnings
+
+    return None, []

divbase_cli/cli_commands/shared_args_options.py

@@ -0,0 +1,23 @@
+"""
+To avoid potential problems with circular imports, we can put shared typer args + options (etc...) here
+
+If you have something that is only used in one of the cli subcommands, don't move it here.
+"""
+
+import typer
+
+PROJECT_NAME_OPTION = typer.Option(
+    None,
+    "--project",
+    "-p",
+    help="Name of the DivBase project, if not provided uses the default in your DivBase config file",
+    show_default=False,
+)
+
+
+FORMAT_AS_TSV_OPTION = typer.Option(
+    False,
+    "--tsv",
+    "-t",
+    help="If set, will print the output in .TSV format for easier programmatic parsing.",
+)

divbase_cli/cli_commands/task_history_cli.py

@@ -0,0 +1,125 @@
+"""
+Task history subcommand for the DivBase CLI.
+
+Submits a query for fetching the Celery task history for the user to the DivBase API.
+
+"""
+
+import logging
+
+import typer
+
+from divbase_cli.cli_commands.shared_args_options import FORMAT_AS_TSV_OPTION
+from divbase_cli.config_resolver import ensure_logged_in, resolve_project, resolve_url_for_non_project_specific_commands
+from divbase_cli.display_task_history import TaskHistoryDisplayManager
+from divbase_cli.user_auth import make_authenticated_request
+from divbase_cli.user_config import load_user_config
+from divbase_lib.api_schemas.task_history import TaskHistoryResult
+
+logger = logging.getLogger(__name__)
+
+
+task_history_app = typer.Typer(
+    help="Get the task history of query jobs submitted by the user to the DivBase API.",
+    no_args_is_help=True,
+)
+
+
+@task_history_app.command("user")
+def list_task_history_for_user(
+    format_output_as_tsv: bool = FORMAT_AS_TSV_OPTION,
+    limit: int = typer.Option(10, help="Maximum number of tasks to display in the terminal. Sorted by recency."),
+    project: str | None = typer.Option(
+        None, help="Optional project name to filter the user's task history by project."
+    ),
+):
+    """
+    Check status of all tasks submitted by the user. Displays the latest 10 tasks by default, unless --limit is specified. Can be filtered by project name.
+    """
+    # TODO add option to sort ASC/DESC by task timestamp
+    divbase_url = resolve_url_for_non_project_specific_commands()
+
+    if project:
+        task_history_response = make_authenticated_request(
+            method="GET",
+            divbase_base_url=divbase_url,
+            api_route=f"v1/task-history/tasks/user/projects/{project}",
+        )
+    else:
+        task_history_response = make_authenticated_request(
+            method="GET",
+            divbase_base_url=divbase_url,
+            api_route="v1/task-history/tasks/user",
+        )
+
+    task_history_data = [TaskHistoryResult(**item) for item in task_history_response.json()]
+
+    config = load_user_config()
+    TaskHistoryDisplayManager(
+        task_items=task_history_data,
+        user_email=config.logged_in_email,
+        project_name=project,
+        mode="user_project" if project else "user",
+        display_limit=limit,
+        format_output_as_tsv=format_output_as_tsv,
+    ).print_task_history()
+
+
+@task_history_app.command("id")
+def task_history_by_id(
+    task_id: int | None = typer.Argument(..., help="Task ID to check the status of a specific query job."),
+    format_output_as_tsv: bool = FORMAT_AS_TSV_OPTION,
+):
+    """
+    Check status of a specific task submitted by the user by its task ID.
+    """
+    divbase_url = resolve_url_for_non_project_specific_commands()
+
+    task_history_response = make_authenticated_request(
+        method="GET",
+        divbase_base_url=divbase_url,
+        api_route=f"v1/task-history/tasks/{task_id}",
+    )
+    task_history_data = [TaskHistoryResult(**item) for item in task_history_response.json()]
+
+    TaskHistoryDisplayManager(
+        task_items=task_history_data,
+        user_email=None,
+        project_name=None,
+        mode="id",
+        format_output_as_tsv=format_output_as_tsv,
+    ).print_task_history()
+
+
+@task_history_app.command("project")
+def list_task_history_for_project(
+    project: str = typer.Argument(
+        None,
+        help="Project name to check the task history for. Leave blank to use the default project set in your config.",
+    ),
+    limit: int = typer.Option(10, help="Maximum number of tasks to display in the terminal. Sorted by recency."),
+    format_output_as_tsv: bool = FORMAT_AS_TSV_OPTION,
+):
+    """
+    Check status of all tasks submitted for a project. Requires a manager role in the project. Displays the latest 10 tasks by default, unless --limit is specified.
+    """
+    # TODO add option to sort ASC/DESC by task timestamp
+    project_config = resolve_project(project_name=project)
+    logged_in_url = ensure_logged_in(desired_url=project_config.divbase_url)
+
+    task_history_response = make_authenticated_request(
+        method="GET",
+        divbase_base_url=logged_in_url,
+        api_route=f"v1/task-history/projects/{project_config.name}",
+    )
+
+    task_history_data = [TaskHistoryResult(**item) for item in task_history_response.json()]
+
+    TaskHistoryDisplayManager(
+        task_items=task_history_data,
+        user_email=None,
+        project_name=project_config.name,
+        mode="project",
+        display_limit=limit,
+        format_output_as_tsv=format_output_as_tsv,
+    ).print_task_history()

divbase_cli/cli_commands/user_config_cli.py

@@ -0,0 +1,145 @@
+"""
+config subcommand for the divbase-cli package.
+
+Controls the user config file stored at "~/.config/.divbase_tools.yaml" (unless specified otherwise).
+"""
+
+import typer
+from rich import print
+from rich.console import Console
+from rich.table import Table
+
+from divbase_cli.cli_config import cli_settings
+from divbase_cli.user_config import (
+    load_user_config,
+)
+
+config_app = typer.Typer(help="Manage your user configuration file for the DivBase CLI.", no_args_is_help=True)
+
+
+@config_app.command("add")
+def add_project_command(
+    name: str = typer.Argument(..., help="Name of the project to add to your config file."),
+    divbase_url: str = typer.Option(
+        cli_settings.DIVBASE_API_URL,
+        "--divbase-url",
+        "-u",
+        help="DivBase API URL associated with this project.",
+    ),
+    make_default: bool = typer.Option(
+        False,
+        "--default",
+        "-d",
+        help="Set this project as the default project in your config file.",
+    ),
+):
+    """Add a new project to your user configuration file."""
+    config = load_user_config()
+    project = config.add_project(
+        name=name,
+        divbase_url=divbase_url,
+        is_default=make_default,
+    )
+
+    print(f"Project: '{project.name}' added to your config.")
+    print(f"The URL: {project.divbase_url} was set as the DivBase API URL for this project.")
+
+    if make_default:
+        print(f"Project '{project.name}' is now set as your default project")
+    else:
+        print(f"To make '{project.name}' your default project you can run: 'divbase config set-default {project.name}'")
+
+
+@config_app.command("rm")
+def remove_project_command(
+    name: str = typer.Argument(..., help="Name of the project to remove from your user configuration file."),
+):
+    """Remove a project from your user configuration file."""
+    config = load_user_config()
+    removed_project = config.remove_project(name)
+
+    if not removed_project:
+        print(f"Nothing to do, the project '{name}' was not found in your user config")
+    else:
+        print(f"The project '{removed_project}' was removed from your config.")
+
+
+@config_app.command("set-default")
+def set_default_project_command(
+    name: str = typer.Argument(..., help="Name of the project to add to the user configuration file."),
+):
+    """Set your default project to use in all divbase-cli commands."""
+    config = load_user_config()
+    default_project_name = config.set_default_project(name=name)
+    print(f"Default project is now set to '{default_project_name}'.")
+
+
+@config_app.command("show-default")
+def show_default_project_command() -> None:
+    """Print the currently set default project to the console."""
+    config = load_user_config()
+
+    if config.default_project:
+        print(config.default_project)
+    else:
+        print("No default project is set in the user configuration file.")
+
+
+@config_app.command("set-dload-dir")
+def set_default_dload_dir_command(
+    download_dir: str = typer.Argument(
+        ...,
+        help="""Set the default directory to download files to. 
+        By default files are downloaded to the current working directory.
+        You can specify an absolute path. 
+        You can use '.' to refer to the directory you run the command from.""",
+    ),
+):
+    """Set the default download dir"""
+    config = load_user_config()
+    dload_dir = config.set_default_download_dir(download_dir=download_dir)
+    if dload_dir == ".":
+        print("The default download directory will be whereever you run the command from.")
+    else:
+        print(f"The default download directory is now set to: {dload_dir}.")
+
+
+@config_app.command("show")
+def show_user_config():
+    """Pretty print the contents of your current config file."""
+    config = load_user_config()
+    console = Console()
+
+    console.print(
+        f"[bold]Your DivBase user configuration file's contents located at:[/bold] '{cli_settings.CONFIG_PATH.resolve()}'\n"
+    )
+
+    if not config.default_download_dir:
+        dload_dir_info = "Not specified, meaning the working directory of wherever you run the download command from."
+    elif config.default_download_dir == ".":
+        dload_dir_info = "Working directory of wherever you run the download command from."
+    else:
+        dload_dir_info = config.default_download_dir
+    console.print(f"[bold]Default Download Directory:[/bold] '{dload_dir_info}'")
+
+    if config.logged_in_url and config.logged_in_email:
+        console.print(f"[bold]You're logged into a DivBase server at URL:[/bold] '{config.logged_in_url}'")
+        console.print(f"[bold]Logged in with email:[/bold] '{config.logged_in_email}'")
+    else:
+        console.print("[bold]You're not logged into any DivBase server.[/bold]")
+
+    if not config.projects:
+        console.print("[bold]No projects defined in your user config file.[/bold]")
+        console.print("You can add a project using the command: 'divbase-cli config add <project_name>'")
+        return
+
+    table = Table(title="\nProjects in your DivBase CLI user config file")
+    table.add_column("Project Name", style="cyan")
+    table.add_column("DivBase URL", style="green")
+    table.add_column("Is default", style="yellow")
+
+    for project in config.projects:
+        is_default = "Yes" if project.name == config.default_project else ""
+        table.add_row(project.name, project.divbase_url, is_default)
+
+    console.print(table)