qbraid-cli 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

qbraid_cli/handlers.py

@@ -0,0 +1,168 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module providing application support utilities, including abstractions for error handling
+and executing operations with progress tracking within the qBraid CLI.
+
+"""
+
+import traceback
+from pathlib import Path
+from typing import Any, Callable, List, Optional, Union
+
+import typer
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from .exceptions import DEFAULT_ERROR_MESSAGE, QbraidException
+
+
+def handle_error(
+    error_type: Optional[str] = None, message: Optional[str] = None, include_traceback: bool = True
+) -> None:
+    """Generic CLI error handling helper function.
+
+    This function handles errors by printing a styled error message to stderr and optionally
+    including a traceback. It then exits the application with a non-zero status code, indicating
+    an error.
+
+    Args:
+        error_type (Optional[str]): The type of the error to be displayed. Defaults to "Error" if
+                                    not specified.
+        message (Optional[str]): The error message to be displayed. If not specified, a default
+                                 error message is used.
+        include_traceback (bool): If True, include the traceback of the exception in the output.
+                                  Defaults to True.
+
+    Raises:
+        typer.Exit: Exits the application with a status code of 1 to indicate an error.
+    """
+    error_type = error_type or "Error"
+    message = message or DEFAULT_ERROR_MESSAGE
+    error_prefix = typer.style(f"{error_type}:", fg=typer.colors.RED, bold=True)
+    full_message = f"\n{error_prefix} {message}\n"
+    if include_traceback:
+        tb_string = traceback.format_exc()
+        # TODO: find out reason for weird traceback emitted from
+        # qbraid jobs enable/disable when library not installed.
+        # For now, if matches, just don't print it.
+        if tb_string.strip() != "NoneType: None":
+            full_message += f"\n{tb_string}"
+    typer.echo(full_message, err=True)
+    raise typer.Exit(code=1)
+
+
+def handle_filesystem_operation(operation: Callable[[], None], path: Path) -> None:
+    """
+    Executes a filesystem operation with error handling.
+
+    Args:
+        operation (Callable[[], None]): The operation to be executed. This should be a callable that
+                                        performs the desired filesystem operation, such as creating
+                                        directories or writing files.
+        path (Path): The path involved in the operation, used for error messaging.
+
+    Raises:
+        QbraidException: If a PermissionError or OSError occurs during the operation.
+    """
+    try:
+        operation()
+    except PermissionError as err:
+        raise QbraidException(f"Permission denied: Unable to write to {path}.") from err
+    except OSError as err:
+        raise QbraidException(f"Failed to save configuration to {path}: {err.strerror}") from err
+
+
+def run_progress_task(
+    operation: Callable[..., Any],
+    *args,
+    description: Optional[str] = None,
+    error_message: Optional[str] = None,
+    **kwargs,
+) -> Any:
+    """
+    Executes a given operation while displaying its progress.
+
+    This function abstracts the setup and update of progress tasks, allowing for a
+    uniform interface for task execution with progress tracking. It supports custom
+    error messages and utilizes the rich library for console output.
+
+    Args:
+        operation (Callable[..., Any]): The operation to be executed. This can be any callable
+                                        that performs the task's work.
+        *args: Variable length argument list for the operation.
+        description (optional, str): The description of the task to display in the progress bar.
+        error_message (optional, str): Custom error message to display if the operation.
+                                       fails. Defaults to None, in which case the
+                                       exception's message is used.
+        **kwargs: Arbitrary keyword arguments for the operation.
+
+    Returns:
+        Any: The result of the operation, if successful.
+
+    Raises:
+        typer.Exit: If the operation fails, after displaying the error message using typer.secho.
+    """
+    console = Console()
+    with Progress(
+        "[progress.description]{task.description}",
+        SpinnerColumn(),
+        TextColumn("{task.fields[status]}"),
+        console=console,
+    ) as progress:
+        description = description if description else "Fetching..."
+        task = progress.add_task(description, status="In Progress", total=None)
+        try:
+            result = operation(*args, **kwargs)
+            progress.update(task, completed=100, status="Done")
+            return result
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            progress.update(task, completed=100, status="Failed")
+            custom_message = error_message if error_message else str(e)
+            return handle_error(message=custom_message)
+
+
+def _format_list_items(items: List[str]) -> str:
+    """
+    Formats a list of items as a string with values comma-separated and
+    each item surrounded by single quotes
+
+    Args:
+        items (List[str]): The list of items to format.
+
+    Returns:
+        str: The formatted string.
+    """
+    return ", ".join(f"'{item}'" for item in items)
+
+
+def validate_item(
+    value: Optional[str], allowed_items: List[str], item_type: str
+) -> Union[str, None]:
+    """
+    Generic item validation function.
+
+    Args:
+        value (optional, str): The value to validate.
+        allowed_items (List[str]): A list of allowed items.
+        item_type (str): A description of the item type (e.g., 'provider', 'status', 'type') for
+                         error messages.
+
+    Returns:
+        Union[str, None]: The validated value, in its original case as specified in the
+                          allowed_items list, or None if the value is None.
+
+    Raises:
+        typer.BadParameter: If the value is not in the allowed_items list.
+    """
+    if value is None:
+        return None
+
+    items_lower_to_original = {item.lower(): item for item in allowed_items}
+
+    value_lower = value.lower()
+    if value_lower not in items_lower_to_original:
+        items_formatted = _format_list_items(allowed_items)
+        raise typer.BadParameter(f"{item_type.capitalize()} must be one of {items_formatted}.")
+    return items_lower_to_original[value_lower]

qbraid_cli/jobs/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining the qbraid jobs namespace
+
+"""
+
+from .app import jobs_app

qbraid_cli/jobs/app.py

@@ -0,0 +1,149 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining commands in the 'qbraid jobs' namespace.
+
+"""
+from typing import Any, Callable, Dict, Tuple
+
+import typer
+from rich.console import Console
+
+from qbraid_cli.handlers import handle_error, run_progress_task
+from qbraid_cli.jobs.toggle_braket import disable_braket, enable_braket
+from qbraid_cli.jobs.validation import handle_jobs_state, run_progress_get_state, validate_library
+
+jobs_app = typer.Typer(help="Manage qBraid quantum jobs.")
+
+
+@jobs_app.command(name="enable")
+def jobs_enable(
+    library: str = typer.Argument(
+        ..., help="Software library with quantum jobs support.", callback=validate_library
+    ),
+    auto_confirm: bool = typer.Option(
+        False, "--yes", "-y", help="Automatically answer 'yes' to all prompts"
+    ),
+) -> None:
+    """Enable qBraid Quantum Jobs."""
+
+    def enable_action():
+        if library == "braket":
+            enable_braket(auto_confirm=auto_confirm)
+        else:
+            raise RuntimeError(f"Unsupported device library: '{library}'.")
+
+    handle_jobs_state(library, "enable", enable_action)
+
+
+@jobs_app.command(name="disable")
+def jobs_disable(
+    library: str = typer.Argument(
+        ..., help="Software library with quantum jobs support.", callback=validate_library
+    ),
+    auto_confirm: bool = typer.Option(
+        False, "--yes", "-y", help="Automatically answer 'yes' to all prompts"
+    ),
+) -> None:
+    """Disable qBraid Quantum Jobs."""
+
+    def disable_action():
+        if library == "braket":
+            disable_braket(auto_confirm=auto_confirm)
+        else:
+            raise RuntimeError(f"Unsupported device library: '{library}'.")
+
+    handle_jobs_state(library, "disable", disable_action)
+
+
+@jobs_app.command(name="state")
+def jobs_state(
+    library: str = typer.Argument(
+        default=None,
+        help="Optional: Specify a software library with quantum jobs support to check its status.",
+        callback=validate_library,
+    )
+) -> None:
+    """Display the state of qBraid Quantum Jobs for the current environment."""
+    result: Tuple[str, Dict[str, Tuple[bool, bool]]] = run_progress_get_state(library)
+    python_exe, state_values = result
+    state_values = dict(sorted(state_values.items()))
+
+    console = Console()
+    header_1, header_2 = "Library", "State"
+    max_lib_length = max((len(lib) for lib in state_values.keys()), default=len(header_1))
+    padding = max_lib_length + 9
+
+    console.print(f"Executable: {python_exe}")
+    console.print(f"\n{header_1:<{padding}}{header_2}", style="bold")
+
+    for lib, (installed, enabled) in state_values.items():
+        state_str = (
+            "[green]enabled"
+            if enabled and installed
+            else "[red]disabled" if installed else "[grey70]unavailable"
+        )
+        console.print(f"{lib:<{padding-1}}", state_str, end="\n")
+
+
+@jobs_app.command(name="list")
+def jobs_list(
+    limit: int = typer.Option(
+        10, "--limit", "-l", help="Limit the maximum number of results returned"
+    )
+) -> None:
+    """List qBraid Quantum Jobs."""
+
+    def import_jobs() -> Tuple[Any, Callable]:
+        from qbraid_core.services.quantum import QuantumClient, process_job_data
+
+        client = QuantumClient()
+
+        return client, process_job_data
+
+    result: Tuple[Any, Callable] = run_progress_task(import_jobs)
+    client, process_job_data = result
+    # https://github.com/qBraid/api/issues/644
+    # raw_data = client.search_jobs(query={"numResults": limit})
+    raw_data = client.search_jobs(query={})
+    job_data, msg = process_job_data(raw_data)
+    job_data = job_data[:limit]
+
+    longest_job_id = max(len(item[0]) for item in job_data)
+    spacing = longest_job_id + 5
+    try:
+        console = Console()
+        header_1 = "Job ID"
+        header_2 = "Submitted"
+        header_3 = "Status"
+        console.print(f"\n[bold]{header_1.ljust(spacing)}{header_2.ljust(36)}{header_3}[/bold]")
+        for job_id, submitted, status in job_data:
+            if status == "COMPLETED":
+                status_color = "green"
+            elif status in ["FAILED", "CANCELLED"]:
+                status_color = "red"
+            elif status in [
+                "INITIALIZING",
+                "INITIALIZED",
+                "CREATED",
+                "QUEUED",
+                "VALIDATING",
+                "RUNNING",
+            ]:
+                status_color = "blue"
+            else:
+                status_color = "grey"
+            console.print(
+                f"{job_id.ljust(spacing)}{submitted.ljust(35)}",
+                f"[{status_color}]{status}[/{status_color}]",
+            )
+
+        console.print(f"\n{msg}", style="italic", justify="left")
+
+    except Exception:  # pylint: disable=broad-exception-caught
+        handle_error(message="Failed to fetch quantum jobs.")
+
+
+if __name__ == "__main__":
+    jobs_app()

qbraid_cli/jobs/toggle_braket.py

@@ -0,0 +1,185 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module supporting 'qbraid jobs enable/disable braket' and commands.
+
+"""
+
+import logging
+import os
+import subprocess
+from pathlib import Path
+from typing import Optional, Tuple
+
+import typer
+
+from qbraid_cli.exceptions import QbraidException
+from qbraid_cli.handlers import handle_error, handle_filesystem_operation, run_progress_task
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def get_package_data(package: str) -> Tuple[str, str, str, str]:
+    """Retrieve package version and location data.
+
+    Args:
+        package (str): The name of the package to retrieve data for.
+
+    Returns:
+        Tuple[str, str, str, str]: The installed and latest versions of the package, and the
+                                   local site-packages path where it is / would be installed.
+
+    Raises:
+        QbraidException: If package version or location data cannot be retrieved.
+
+    """
+    # pylint: disable=import-outside-toplevel
+    from qbraid_core.system import (
+        QbraidSystemError,
+        get_active_python_path,
+        get_active_site_packages_path,
+        get_latest_package_version,
+        get_local_package_version,
+    )
+
+    try:
+        python_pathlib = get_active_python_path()
+        site_packages_path = get_active_site_packages_path(python_path=python_pathlib)
+        installed_version = get_local_package_version(package, python_path=python_pathlib)
+        latest_version = get_latest_package_version(package)
+    except QbraidSystemError as err:
+        raise QbraidException("Failed to retrieve required system and/or package metadata") from err
+
+    return installed_version, latest_version, str(site_packages_path), str(python_pathlib)
+
+
+def confirm_updates(
+    mode: str,
+    site_packages_path: str,
+    installed_version: Optional[str] = None,
+    latest_version: Optional[str] = None,
+) -> None:
+    """
+    Prompts the user to proceed with enabling or disabling qBraid Quantum Jobs.
+
+    Args:
+        mode (str): The mode of operation, either "enable" or "disable".
+        site_packages_path (str): The location of the site-packages directory where
+                                  target package(s) will be updated.
+        installed_version (optional, str): The installed version of the target package.
+        latest_version (optional, str): The latest version of the target package available on PyPI.
+
+    Raises:
+        ValueError: If an invalid mode is provided.
+        typer.Exit: If the user declines to proceed with enabling or disabling qBraid Quantum Jobs.
+
+    """
+    core_package = "botocore"
+    versioned_package = "boto3"
+    if mode == "enable":
+        provider = "qBraid"
+        update_msg = f"update {versioned_package} and install"
+    elif mode == "disable":
+        provider = "boto"
+        update_msg = "re-install"
+    else:
+        raise ValueError(f"Invalid mode: {mode}. Expected 'enable' or 'disable'.")
+
+    typer.echo(f"\n==> WARNING: {provider}/{core_package} package required <==")
+    if (
+        installed_version is not None
+        and latest_version is not None
+        and installed_version != latest_version
+    ):
+        typer.echo(f"==> WARNING: A newer version of {versioned_package} exists. <==")
+        typer.echo(f"  current version: {installed_version}")
+        typer.echo(f"  latest version: {latest_version}")
+
+    gerund = mode[:-2].capitalize() + "ing"
+
+    typer.echo(
+        f"\n{gerund} quantum jobs will automatically {update_msg} {provider}/{core_package}, "
+        "which may cause incompatibilities with the amazon-braket-sdk and/or awscli.\n"
+    )
+    typer.echo("## Package Plan ##")
+    if mode == "enable":
+        typer.echo(
+            f"  {versioned_package} location: {os.path.join(site_packages_path, versioned_package)}"
+        )
+    typer.echo(f"  {core_package} location: {os.path.join(site_packages_path, core_package)}\n")
+
+    user_confirmation = typer.confirm("Proceed", default=True)
+    if not user_confirmation:
+        typer.echo("\nqBraidSystemExit: Exiting.")
+        raise typer.Exit()
+
+
+def aws_configure_dummy() -> None:
+    """
+    Initializes AWS configuration and credentials files with placeholder values.
+
+    """
+    from qbraid_core.services.quantum.proxy_braket import aws_configure
+
+    try:
+        handle_filesystem_operation(aws_configure, Path.home() / ".aws")
+    except QbraidException:
+        handle_error(message="Failed to configure qBraid quantum jobs.")
+
+
+def enable_braket(auto_confirm: bool = False):
+    """Enable qBraid quantum jobs for Amazon Braket."""
+    installed, latest, path, python_exe = run_progress_task(
+        get_package_data, "boto3", description="Solving environment..."
+    )
+
+    if not auto_confirm:
+        confirm_updates("enable", path, installed_version=installed, latest_version=latest)
+    typer.echo("")
+
+    aws_configure_dummy()  # TODO: possibly add another confirmation for writing aws config files
+
+    try:
+        subprocess.check_call([python_exe, "-m", "pip", "install", "--upgrade", "boto3"])
+        subprocess.check_call([python_exe, "-m", "pip", "uninstall", "botocore", "-y", "--quiet"])
+        subprocess.check_call(
+            [python_exe, "-m", "pip", "install", "git+https://github.com/qBraid/botocore.git"]
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        handle_error(message="Failed to enable qBraid quantum jobs.")
+
+    typer.secho("\nSuccessfully enabled qBraid quantum jobs.", fg=typer.colors.GREEN, bold=True)
+    typer.secho("\nTo disable, run: \n\n\t$ qbraid jobs disable braket\n")
+
+
+def disable_braket(auto_confirm: bool = False):
+    """Disable qBraid quantum jobs for Amazon Braket."""
+    package = "botocore"
+    installed, latest, path, python_exe = run_progress_task(
+        get_package_data, package, description="Solving environment..."
+    )
+    package = f"{package}~={installed}" if installed < latest else package
+
+    if not auto_confirm:
+        confirm_updates("disable", path)
+    typer.echo("")
+
+    try:
+        subprocess.check_call(
+            [
+                python_exe,
+                "-m",
+                "pip",
+                "install",
+                package,
+                "--force-reinstall",
+            ],
+            stderr=subprocess.DEVNULL,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        handle_error(message="Failed to disable qBraid quantum jobs.")
+
+    typer.secho("\nSuccessfully disabled qBraid quantum jobs.", fg=typer.colors.GREEN, bold=True)
+    typer.secho("\nTo enable, run: \n\n\t$ qbraid jobs enable braket\n")

qbraid_cli/jobs/validation.py

@@ -0,0 +1,93 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module for validating command arguments for qBraid Quantum Jobs.
+
+"""
+import sys
+from typing import Any, Callable, Dict, Optional, Tuple
+
+import typer
+from rich.console import Console
+
+from qbraid_cli.handlers import handle_error, run_progress_task, validate_item
+
+LEGACY_ARGS: Dict[str, str] = {
+    "amazon_braket": "braket",
+    "aws_braket": "braket",
+}
+
+
+def validate_library(value: str) -> str:
+    """Validate quantum jobs library."""
+    # pylint:disable-next=import-outside-toplevel
+    from qbraid_core.services.quantum.proxy import SUPPORTED_QJOB_LIBS
+
+    qjobs_libs = list(SUPPORTED_QJOB_LIBS.keys())
+
+    if value in LEGACY_ARGS:
+        old_value = value
+        value = LEGACY_ARGS[value]
+
+        console = Console()
+        console.print(
+            f"[red]DeprecationWarning:[/red] Argument '{old_value}' "
+            f"is deprecated. Use '{value}' instead.\n"
+        )
+
+    return validate_item(value, qjobs_libs, "Library")
+
+
+def get_state(library: Optional[str] = None) -> Tuple[str, Dict[str, Tuple[bool, bool]]]:
+    """Get the state of qBraid Quantum Jobs for the specified library."""
+    from qbraid_core.services.quantum import QuantumClient
+
+    jobs_state = QuantumClient.qbraid_jobs_state(device_lib=library)
+
+    python_exe: str = jobs_state.get("exe", sys.executable)
+    libs_state: Dict[str, Any] = jobs_state.get("libs", {})
+
+    state_values = {
+        lib: (state["supported"], state["enabled"]) for lib, state in libs_state.items()
+    }
+
+    return python_exe, state_values
+
+
+def run_progress_get_state(
+    library: Optional[str] = None,
+) -> Tuple[str, Dict[str, Tuple[bool, bool]]]:
+    """Run get state function with rich progress UI."""
+    return run_progress_task(
+        get_state,
+        library,
+        description="Collecting package metadata...",
+        error_message=f"Failed to collect {library} package metadata.",
+    )
+
+
+def handle_jobs_state(
+    library: str,
+    action: str,  # 'enable' or 'disable'
+    action_callback: Callable[[], None],
+) -> None:
+    """Handle the common logic for enabling or disabling qBraid Quantum Jobs."""
+    _, state_values = run_progress_get_state(library)
+    installed, enabled = state_values[library]
+
+    if not installed:
+        handle_error(
+            message=f"{library} not installed."
+        )  # TODO: Provide command to install library?
+    if (enabled and action == "enable") or (not enabled and action == "disable"):
+        action_color = "green" if enabled else "red"
+        console = Console()
+        console.print(
+            f"\nqBraid quantum jobs already [bold {action_color}]{action}d[/bold {action_color}] "
+            f"for [magenta]{library}[/magenta].\n\nCheck the state of all quantum jobs "
+            "libraries in this environment with: \n\n\t$ qbraid jobs state\n"
+        )
+        raise typer.Exit()
+
+    action_callback()  # Perform the specific enable/disable action

qbraid_cli/kernels/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining the qbraid kernels namespace
+
+"""
+
+from .app import kernels_app