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

qbraid_cli/_version.py

@@ -1,7 +1,16 @@
-"""
-Module containing version information
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
 
-Version number (major.minor.patch[-label])
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
 
-"""
-__version__ = "0.7.0"
+__version__ = version = '0.8.0'
+__version_tuple__ = version_tuple = (0, 8, 0)

qbraid_cli/admin/__init__.py

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

qbraid_cli/admin/app.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining commands in the 'qbraid admin' namespace.
+
+"""
+
+from typing import List
+
+import typer
+
+from qbraid_cli.admin.headers import check_and_fix_headers
+from qbraid_cli.admin.validation import validate_header_type, validate_paths_exist
+
+# disable pretty_exceptions_show_locals to avoid printing sensative information in the traceback
+admin_app = typer.Typer(
+    help="CI/CD commands for qBraid maintainers.",
+    pretty_exceptions_show_locals=False,
+)
+
+
+@admin_app.command(name="headers")
+def admin_headers(
+    src_paths: List[str] = typer.Argument(
+        ..., help="Source file or directory paths to verify.", callback=validate_paths_exist
+    ),
+    header_type: str = typer.Option(
+        "default",
+        "--type",
+        "-t",
+        help="Type of header to use ('default' or 'gpl').",
+        callback=validate_header_type,
+    ),
+    skip_files: List[str] = typer.Option(
+        [], "--skip", "-s", help="Files to skip during verification.", callback=validate_paths_exist
+    ),
+    fix: bool = typer.Option(
+        False, "--fix", "-f", help="Whether to fix the headers instead of just verifying."
+    ),
+):
+    """
+    Verifies and optionally fixes qBraid headers in specified files and directories.
+
+    """
+    check_and_fix_headers(src_paths, header_type=header_type, skip_files=skip_files, fix=fix)
+
+
+if __name__ == "__main__":
+    admin_app()

qbraid_cli/admin/headers.py

@@ -0,0 +1,193 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Script to verify qBraid copyright file headers
+
+"""
+import os
+import sys
+from typing import List, Optional
+
+from rich.console import Console
+
+# pylint: disable=too-many-branches,too-many-statements
+
+DEFAULT_HEADER = """# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+"""
+
+DEFAULT_HEADER_GPL = """# Copyright (C) 2024 qBraid
+#
+# This file is part of the qBraid-SDK
+#
+# The qBraid-SDK is free software released under the GNU General Public License v3
+# or later. You can redistribute and/or modify it under the terms of the GPL v3.
+# See the LICENSE file in the project root or <https://www.gnu.org/licenses/gpl-3.0.html>.
+#
+# THERE IS NO WARRANTY for the qBraid-SDK, as per Section 15 of the GPL v3.
+"""
+
+HEADER_TYPES = {
+    "default": DEFAULT_HEADER,
+    "gpl": DEFAULT_HEADER_GPL,
+}
+
+
+def check_and_fix_headers(
+    src_paths: List[str],
+    header_type: str = "default",
+    skip_files: Optional[List[str]] = None,
+    fix: bool = False,
+) -> None:
+    """Script to add or verify qBraid copyright file headers"""
+    try:
+        header = HEADER_TYPES[header_type]
+    except KeyError as err:
+        raise ValueError(
+            f"Invalid header type: {HEADER_TYPES}. Expected one of {list(HEADER_TYPES.keys())}"
+        ) from err
+
+    for path in src_paths:
+        if not os.path.exists(path):
+            sys.stderr.write(
+                f"Usage: qbraid verify_headers [OPTIONS] SRC ...\n"
+                f"Try 'qbraid verify_headers --help' for help.\n\n"
+                f"Error: Invalid value for 'SRC ...': Path '{path}' does not exist.\n"
+            )
+            sys.exit(1)
+
+    header_2023 = header.replace("2024", "2023")
+
+    skip_files = skip_files or []
+
+    failed_headers = []
+    fixed_headers = []
+
+    console = Console()
+
+    def should_skip(file_path: str, content: str) -> bool:
+        if file_path in skip_files:
+            return True
+
+        if os.path.basename(file_path) == "__init__.py":
+            return not content.strip()
+
+        skip_header_tag = "# qbraid: skip-header"
+        line_number = 0
+
+        for line in content.splitlines():
+            line_number += 1
+            if 5 <= line_number <= 30 and skip_header_tag in line:
+                return True
+            if line_number > 30:
+                break
+
+        return False
+
+    def replace_or_add_header(file_path: str, fix: bool = False) -> None:
+        with open(file_path, "r", encoding="ISO-8859-1") as f:
+            content = f.read()
+
+        # This finds the start of the actual content after skipping initial whitespace and comments.
+        lines = content.splitlines()
+        first_non_comment_line_index = next(
+            (i for i, line in enumerate(lines) if not line.strip().startswith("#")), None
+        )
+
+        # Prepare the content by stripping leading and trailing whitespace and separating into lines
+        actual_content = (
+            "\n".join(lines[first_non_comment_line_index:]).strip()
+            if first_non_comment_line_index is not None
+            else ""
+        )
+
+        # Check if the content already starts with the header or if the file should be skipped
+        if (
+            content.lstrip().startswith(header)
+            or content.lstrip().startswith(header_2023)
+            or should_skip(file_path, content)
+        ):
+            return
+
+        if not fix:
+            failed_headers.append(file_path)
+        else:
+            # Form the new content by combining the header, one blank line, and the actual content
+            new_content = header.strip() + "\n\n" + actual_content
+            with open(file_path, "w", encoding="ISO-8859-1") as f:
+                f.write(new_content)
+            fixed_headers.append(file_path)
+
+    def process_files_in_directory(directory: str, fix: bool = False) -> int:
+        count = 0
+        if not os.path.isdir(directory):
+            return count
+        for root, _, files in os.walk(directory):
+            for file in files:
+                if file.endswith(".py"):
+                    file_path = os.path.join(root, file)
+                    replace_or_add_header(file_path, fix)
+                    count += 1
+        return count
+
+    checked = 0
+    for item in src_paths:
+        if os.path.isdir(item):
+            checked += process_files_in_directory(item, fix)
+        elif os.path.isfile(item) and item.endswith(".py"):
+            replace_or_add_header(item, fix)
+            checked += 1
+        else:
+            failed_headers.append(item)
+            print(f"File or directory not found: {item}")
+
+    if not fix:
+        if failed_headers:
+            for file in failed_headers:
+                console.print(f"[bold]would fix {file}[/bold]")
+            num_failed = len(failed_headers)
+            num_passed = checked - num_failed
+            s1, s2 = ("", "s") if num_failed == 1 else ("s", "")
+            s_passed = "" if num_passed == 1 else "s"
+            console.print("[bold]\nOh no![/bold] 💥 💔 💥")
+            if num_passed > 0:
+                punc = ", "
+                passed_msg = f"[blue]{num_passed}[/blue] file{s_passed} would be left unchanged."
+            else:
+                punc = "."
+                passed_msg = ""
+
+            failed_msg = f"[bold][blue]{num_failed}[/blue] file{s1} need{s2} updating{punc}[/bold]"
+            console.print(f"{failed_msg}{passed_msg}")
+        elif checked == 0:
+            console.print("[bold]No Python files present. Nothing to do[/bold] 😴")
+        else:
+            s_checked = "" if checked == 1 else "s"
+            console.print("[bold]All done![/bold] ✨ 🚀 ✨")
+            console.print(f"[blue]{checked}[/blue] file{s_checked} would be left unchanged.")
+
+    else:
+        for file in fixed_headers:
+            console.print(f"[bold]fixed {file}[/bold]")
+        num_fixed = len(fixed_headers)
+        num_ok = checked - num_fixed
+        s_fixed = "" if num_fixed == 1 else "s"
+        s_ok = "" if num_ok == 1 else "s"
+        console.print("\n[bold]All done![/bold] ✨ 🚀 ✨")
+        if num_ok > 0:
+            punc = ", "
+            unchanged_msg = f"[blue]{num_ok}[/blue] file{s_ok} left unchanged."
+        else:
+            punc = "."
+            unchanged_msg = ""
+
+        if num_fixed > 0:
+            fixed_msg = f"[bold][blue]{num_fixed}[/blue] file{s_fixed} fixed{punc}[/bold]"
+        else:
+            fixed_msg = ""
+
+        if fixed_msg or unchanged_msg:
+            console.print(f"{fixed_msg}{unchanged_msg}")
+        else:
+            console.print("[bold]No Python files present. Nothing to do[/bold] 😴")

qbraid_cli/admin/validation.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module for validating command arguments for qBraid admin commands.
+
+"""
+
+import os
+from typing import List
+
+import typer
+
+from qbraid_cli.admin.headers import HEADER_TYPES
+from qbraid_cli.handlers import _format_list_items, validate_item
+
+
+def validate_header_type(value: str) -> str:
+    """Validate header type."""
+    header_types = list(HEADER_TYPES.keys())
+    return validate_item(value, header_types, "Header type")
+
+
+def validate_paths_exist(paths: List[str]) -> List[str]:
+    """Verifies that each path in the provided list exists."""
+    non_existent_paths = [path for path in paths if not os.path.exists(path)]
+    if non_existent_paths:
+        if len(non_existent_paths) == 1:
+            raise typer.BadParameter(f"Path '{non_existent_paths[0]}' does not exist")
+        raise typer.BadParameter(
+            f"The following paths do not exist: {_format_list_items(non_existent_paths)}"
+        )
+    return paths

qbraid_cli/configure/__init__.py

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

qbraid_cli/configure/actions.py

@@ -0,0 +1,111 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining actions invoked by 'qbraid configure' command(s).
+
+"""
+
+import configparser
+import re
+from copy import deepcopy
+from typing import Dict, Optional
+
+import typer
+from qbraid_core.config import (
+    DEFAULT_CONFIG_SECTION,
+    DEFAULT_ENDPOINT_URL,
+    USER_CONFIG_PATH,
+    load_config,
+    save_config,
+)
+from rich.console import Console
+
+from qbraid_cli.handlers import handle_filesystem_operation
+
+
+def validate_input(key: str, value: str) -> str:
+    """Validate the user input based on the key.
+
+    Args:
+        key (str): The configuration key
+        value (str): The user input value
+
+    Returns:
+        str: The validated value
+
+    Raises:
+        typer.BadParameter: If the value is invalid
+    """
+    if key == "url":
+        if not re.match(r"^https?://\S+$", value):
+            raise typer.BadParameter("Invalid URL format.")
+    elif key == "email":
+        if not re.match(r"^\S+@\S+\.\S+$", value):
+            raise typer.BadParameter("Invalid email format.")
+    elif key == "api-key":
+        if not re.match(r"^[a-zA-Z0-9]{11}$", value):
+            raise typer.BadParameter("Invalid API key format.")
+    return value
+
+
+def prompt_for_config(
+    config: configparser.ConfigParser,
+    section: str,
+    key: str,
+    default_values: Optional[Dict[str, str]] = None,
+) -> str:
+    """Prompt the user for a configuration setting, showing the current value as default."""
+    default_values = default_values or {}
+    current_value = config.get(section, key, fallback=default_values.get(key, ""))
+    display_value = "None" if not current_value else current_value
+    hide_input = False
+    show_default = True
+
+    if section == DEFAULT_CONFIG_SECTION:
+        if key == "url":
+            return current_value
+
+        if key == "api-key":
+            if current_value:
+                display_value = "*" * len(current_value[:-4]) + current_value[-4:]
+            hide_input = True
+            show_default = False
+
+    new_value = typer.prompt(
+        f"Enter {key}", default=display_value, show_default=show_default, hide_input=hide_input
+    ).strip()
+
+    if new_value == display_value:
+        return current_value
+
+    return validate_input(key, new_value)
+
+
+def default_action(section: str = DEFAULT_CONFIG_SECTION):
+    """Configure qBraid CLI options."""
+    config = load_config()
+    original_config = deepcopy(config)
+
+    if section not in config:
+        config[section] = {}
+
+    default_values = {"url": DEFAULT_ENDPOINT_URL}
+
+    config[section]["url"] = prompt_for_config(config, section, "url", default_values)
+    config[section]["api-key"] = prompt_for_config(config, section, "api-key", default_values)
+
+    for key in list(config[section]):
+        if not config[section][key]:
+            del config[section][key]
+
+    console = Console()
+    if config == original_config:
+        console.print("\n[bold grey70]Configuration saved, unchanged.")
+    else:
+
+        def _save_config():
+            save_config(config)
+
+        handle_filesystem_operation(_save_config, USER_CONFIG_PATH)
+        console.print("\n[bold green]Configuration updated successfully.")

qbraid_cli/configure/app.py

@@ -0,0 +1,77 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining commands in the 'qbraid configure' namespace.
+
+"""
+
+import typer
+from rich.console import Console
+
+from qbraid_cli.configure.actions import default_action
+
+# disable pretty_exceptions_show_locals to avoid printing sensative information in the traceback
+configure_app = typer.Typer(
+    help="Configure qBraid CLI options.", pretty_exceptions_show_locals=False
+)
+
+
+@configure_app.callback(invoke_without_command=True)
+def configure(ctx: typer.Context):
+    """
+    Prompts user for configuration values such as your qBraid API Key.
+    If your config file does not exist (the default location is ~/.qbraid/qbraidrc),
+    the qBraid CLI will create it for you. To keep an existing value, hit enter
+    when prompted for the value. When you are prompted for information, the current
+    value will be displayed in [brackets]. If the config item has no value, it be
+    displayed as [None].
+
+    """
+    if ctx.invoked_subcommand is None:
+        default_action()
+
+
+@configure_app.command(name="set")
+def configure_set(
+    name: str = typer.Argument(..., help="Config name"),
+    value: str = typer.Argument(..., help="Config value"),
+    profile: str = typer.Option("default", help="Profile name"),
+):
+    """Set configuration value in qbraidrc file."""
+    # pylint: disable-next=import-outside-toplevel
+    from qbraid_core.config import load_config, save_config
+
+    config = load_config()
+
+    if profile not in config:
+        config[profile] = {}
+
+    config[profile][name] = value
+
+    save_config(config)
+    typer.echo("Configuration updated successfully.")
+
+
+@configure_app.command(name="magic")
+def configure_magic():
+    """Enable qBraid IPython magic commands."""
+    # pylint: disable-next=import-outside-toplevel
+    from qbraid_core.services.environments import add_magic_config
+
+    add_magic_config()
+
+    console = Console()
+
+    in_1 = (
+        "[green]In [[/green][yellow]1[/yellow][green]]:[/green] [blue]%[/blue]load_ext qbraid_magic"
+    )
+    in_2 = "[green]In [[/green][yellow]2[/yellow][green]]:[/green] [blue]%[/blue]qbraid"
+
+    console.print("\nSuccessfully configured qBraid IPython magic commands.\n")
+    console.print("You can now use the qBraid-CLI from inside a Jupyter notebook as follows:")
+    console.print(f"\n\t{in_1}\n\n\t{in_2}\n")
+
+
+if __name__ == "__main__":
+    configure_app()

qbraid_cli/credits/__init__.py

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

qbraid_cli/credits/app.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining commands in the 'qbraid credits' namespace.
+
+"""
+
+import typer
+
+from qbraid_cli.handlers import run_progress_task
+
+credits_app = typer.Typer(help="Manage qBraid credits.")
+
+
+@credits_app.command(name="value")
+def credits_value():
+    """Get number of qBraid credits remaining."""
+
+    def get_credits() -> float:
+        from qbraid_core import QbraidClient
+
+        client = QbraidClient()
+        return client.user_credits_value()
+
+    qbraid_credits: float = run_progress_task(get_credits)
+    credits_text = typer.style(f"{qbraid_credits:.2f}", fg=typer.colors.GREEN, bold=True)
+    typer.secho(f"\nqBraid credits: {credits_text}")
+
+
+if __name__ == "__main__":
+    credits_app()

qbraid_cli/devices/__init__.py

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

qbraid_cli/devices/app.py

@@ -0,0 +1,80 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining commands in the 'qbraid devices' namespace.
+
+"""
+
+from typing import Any, Callable, Optional, Tuple
+
+import typer
+from rich.console import Console
+
+from qbraid_cli.devices.validation import validate_provider, validate_status, validate_type
+from qbraid_cli.handlers import run_progress_task
+
+devices_app = typer.Typer(help="Manage qBraid quantum devices.")
+
+
+@devices_app.command(name="list")
+def devices_list(  # pylint: disable=too-many-branches
+    status: Optional[str] = typer.Option(
+        None, "--status", "-s", help="'ONLINE'|'OFFLINE'|'RETIRED'", callback=validate_status
+    ),
+    device_type: Optional[str] = typer.Option(
+        None, "--type", "-t", help="'QPU'|'SIMULATOR'", callback=validate_type
+    ),
+    provider: Optional[str] = typer.Option(
+        None,
+        "--provider",
+        "-p",
+        help="'AWS'|'IBM'|'IonQ'|'Rigetti'|'OQC'|'QuEra'",
+        callback=validate_provider,
+    ),
+) -> None:
+    """List qBraid quantum devices."""
+    filters = {}
+    if status:
+        filters["status"] = status
+    if device_type:
+        filters["type"] = "Simulator" if device_type == "SIMULATOR" else device_type
+    if provider:
+        filters["provider"] = provider
+
+    def import_devices() -> Tuple[Any, Callable]:
+        from qbraid_core.services.quantum import QuantumClient, process_device_data
+
+        client = QuantumClient()
+
+        return client, process_device_data
+
+    result: Tuple[Callable, Callable] = run_progress_task(import_devices)
+    client, process_device_data = result
+    raw_data = client.search_devices(filters)
+    device_data, msg = process_device_data(raw_data)
+
+    console = Console()
+    header_1 = "Provider"
+    header_2 = "Device Name"
+    header_3 = "ID"
+    header_4 = "Status"
+    console.print(
+        f"\n[bold]{header_1.ljust(12)}{header_2.ljust(35)}{header_3.ljust(41)}{header_4}[/bold]"
+    )
+    for device_provider, device_name, device_id, device_status in device_data:
+        if device_status == "ONLINE":
+            status_color = "green"
+        elif device_status == "OFFLINE":
+            status_color = "red"
+        else:
+            status_color = "grey"
+        console.print(
+            f"{device_provider.ljust(12)}{device_name.ljust(35)}{device_id.ljust(40)}",
+            f"[{status_color}]{device_status}[/{status_color}]",
+        )
+    console.print(f"\n{msg}", style="italic", justify="left")
+
+
+if __name__ == "__main__":
+    devices_app()

qbraid_cli/devices/validation.py

@@ -0,0 +1,26 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module for validating command arguments for qBraid devices commands.
+
+"""
+
+from typing import Optional, Union
+
+from qbraid_cli.handlers import validate_item
+
+
+def validate_status(value: Optional[str]) -> Union[str, None]:
+    """Validate device status query parameter."""
+    return validate_item(value, ["ONLINE", "OFFLINE", "RETIRED"], "Status")
+
+
+def validate_type(value: Optional[str]) -> Union[str, None]:
+    """Validate device type query parameter."""
+    return validate_item(value, ["QPU", "SIMULATOR"], "Type")
+
+
+def validate_provider(value: Optional[str]) -> Union[str, None]:
+    """Validate device provider query parameter."""
+    return validate_item(value, ["AWS", "IBM", "IonQ", "Rigetti", "OQC", "QuEra"], "Provider")

qbraid_cli/envs/__init__.py

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