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

qbraid_cli/envs/activate.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module supporting 'qbraid envs activate' command.
+
+"""
+
+import os
+from pathlib import Path
+
+import typer
+
+
+def find_shell_rc(shell_path: str) -> str:
+    """Finds an existing shell configuration file in the user's home directory."""
+    if "bash" not in shell_path:
+        raise ValueError(f"Unsupported shell: {shell_path}")
+
+    possible_files = [".bashrc", ".bash_profile", ".bash_login"]
+
+    for file_name in possible_files:
+        rc_file = Path.home() / file_name
+        if rc_file.exists():
+            return str(rc_file)
+
+    raise FileNotFoundError(f"No {shell_path} configuration file found in the home directory.")
+
+
+def print_activate_command(venv_path: Path) -> None:
+    """Prints the command to activate the virtual environment with improved formatting."""
+    typer.echo("To activate this environment, use command:\n")
+    if os.name == "nt":
+        # Windows operating system
+        activate_script = venv_path / "Scripts" / "activate"
+        activate_script_ps = venv_path / "Scripts" / "Activate.ps1"
+        typer.echo("\t$ " + str(activate_script))
+        typer.echo("\nOr for PowerShell, use:\n")
+        typer.echo("\t$ " + f"& {activate_script_ps}")
+    else:
+        # Unix-like operating systems (Linux/macOS)
+        activate_script = venv_path / "bin" / "activate"
+        typer.echo("\t$ " + f"source {activate_script}")
+    typer.echo("")
+    raise typer.Exit()
+
+
+def activate_pyvenv(venv_path: Path):
+    """Activate the virtual environment."""
+    shell_path = os.environ.get("SHELL")
+
+    if shell_path is None:
+        print_activate_command(venv_path)
+        return  # Return early since we can't proceed without a shell
+    try:
+        shell_rc = find_shell_rc(shell_path)
+    except (FileNotFoundError, ValueError):
+        print_activate_command(venv_path)
+        return  # Return early since no suitable shell rc file was found
+    bin_path = str(venv_path / "bin")
+
+    os.system(
+        f"cat {shell_rc} {bin_path}/activate > {bin_path}/activate2 && "
+        f"{shell_path} --rcfile {bin_path}/activate2"
+    )

qbraid_cli/envs/app.py

@@ -0,0 +1,270 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining commands in the 'qbraid envs' namespace.
+
+"""
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+import typer
+from rich.console import Console
+
+from qbraid_cli.envs.data_handling import installed_envs_data, request_delete_env, validate_env_name
+from qbraid_cli.handlers import QbraidException, run_progress_task
+
+envs_app = typer.Typer(help="Manage qBraid environments.")
+
+
+@envs_app.command(name="create")
+def envs_create(  # pylint: disable=too-many-statements
+    name: str = typer.Option(
+        ..., "--name", "-n", help="Name of the environment to create", callback=validate_env_name
+    ),
+    description: Optional[str] = typer.Option(
+        None, "--description", "-d", help="Short description of the environment"
+    ),
+    auto_confirm: bool = typer.Option(
+        False, "--yes", "-y", help="Automatically answer 'yes' to all prompts"
+    ),
+) -> None:
+    """Create a new qBraid environment."""
+    from .create import create_qbraid_env_assets, create_venv
+
+    def request_new_env(req_body: Dict[str, str]) -> Dict[str, Any]:
+        """Send request to create new environment and return the slug."""
+        from qbraid_core import QbraidSession, RequestsApiError
+
+        session = QbraidSession()
+
+        try:
+            env_data = session.post("/environments/create", json=req_body).json()
+        except RequestsApiError as err:
+            raise QbraidException("Create environment request failed") from err
+
+        if env_data is None or len(env_data) == 0 or env_data.get("slug") is None:
+            raise QbraidException(
+                "Create environment request responsed with invalid environment data"
+            )
+
+        return env_data
+
+    def gather_local_data() -> Tuple[Path, str]:
+        """Gather environment data and return the slug."""
+        from qbraid_core.services.environments import get_default_envs_paths
+
+        env_path = get_default_envs_paths()[0]
+
+        result = subprocess.run(
+            [sys.executable, "--version"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        python_version = result.stdout or result.stderr
+
+        return env_path, python_version
+
+    req_body = {
+        "name": name,
+        "description": description or "",
+        "tags": "",  # comma separated list of tags
+        "code": "",  # newline separated list of packages
+        "visibility": "private",
+        "kernelName": "",
+        "prompt": "",
+        "origin": "CLI",
+    }
+
+    environment = run_progress_task(
+        request_new_env,
+        req_body,
+        description="Validating request...",
+        error_message="Failed to create qBraid environment",
+    )
+
+    env_path, python_version = run_progress_task(
+        gather_local_data,
+        description="Solving environment...",
+        error_message="Failed to create qBraid environment",
+    )
+
+    slug = environment.get("slug")
+    display_name = environment.get("displayName")
+    prompt = environment.get("prompt")
+    description = environment.get("description")
+    tags = environment.get("tags")
+    kernel_name = environment.get("kernelName")
+
+    slug_path = env_path / slug
+    description = "None" if description == "" else description
+
+    typer.echo("\n\n## qBraid Metadata ##\n")
+    typer.echo(f"  name: {display_name}")
+    typer.echo(f"  description: {description}")
+    typer.echo(f"  tags: {tags}")
+    typer.echo(f"  slug: {slug}")
+    typer.echo(f"  shellPrompt: {prompt}")
+    typer.echo(f"  kernelName: {kernel_name}")
+
+    typer.echo("\n\n## Environment Plan ##\n")
+    typer.echo(f"  location: {slug_path}")
+    typer.echo(f"  version: {python_version}\n")
+
+    user_confirmation = auto_confirm or typer.confirm("Proceed", default=True)
+    typer.echo("")
+    if not user_confirmation:
+        request_delete_env(slug)
+        typer.echo("qBraidSystemExit: Exiting.")
+        raise typer.Exit()
+
+    run_progress_task(
+        create_qbraid_env_assets,
+        slug,
+        prompt,
+        kernel_name,
+        slug_path,
+        description="Generating qBraid assets...",
+        error_message="Failed to create qBraid environment",
+    )
+
+    run_progress_task(
+        create_venv,
+        slug_path,
+        prompt,
+        description="Creating virtual environment...",
+        error_message="Failed to create qBraid environment",
+    )
+
+    console = Console()
+    console.print(
+        f"\n[bold green]Successfully created qBraid environment: "
+        f"[/bold green][bold magenta]{name}[/bold magenta]\n"
+    )
+    typer.echo("# To activate this environment, use")
+    typer.echo("#")
+    typer.echo(f"#     $ qbraid envs activate {name}")
+    typer.echo("#")
+    typer.echo("# To deactivate an active environment, use")
+    typer.echo("#")
+    typer.echo("#     $ deactivate")
+
+
+@envs_app.command(name="remove")
+def envs_remove(
+    name: str = typer.Option(..., "-n", "--name", help="Name of the environment to remove"),
+    auto_confirm: bool = typer.Option(
+        False, "--yes", "-y", help="Automatically answer 'yes' to all prompts"
+    ),
+) -> None:
+    """Delete a qBraid environment."""
+
+    def gather_local_data(env_name: str) -> Tuple[Path, str]:
+        """Get environment path and slug from name (alias)."""
+        installed, aliases = installed_envs_data()
+        for alias, slug in aliases.items():
+            if alias == env_name:
+                path = installed[slug]
+
+                return path, slug
+
+        raise QbraidException(f"Environment '{name}' not found.")
+
+    slug_path, slug = gather_local_data(name)
+
+    confirmation_message = (
+        f"⚠️  Warning: You are about to delete the environment '{name}' "
+        f"located at '{slug_path}'.\n"
+        "This will remove all local packages and permanently delete all "
+        "of its associated qBraid environment metadata.\n"
+        "This operation CANNOT be undone.\n\n"
+        "Are you sure you want to continue?"
+    )
+
+    if auto_confirm or typer.confirm(confirmation_message, abort=True):
+        typer.echo("")
+        run_progress_task(
+            request_delete_env,
+            slug,
+            description="Deleting remote environment data...",
+            error_message="Failed to delete qBraid environment",
+        )
+
+        run_progress_task(
+            shutil.rmtree,
+            slug_path,
+            description="Deleting local environment...",
+            error_message="Failed to delete qBraid environment",
+        )
+        typer.echo(f"\nEnvironment '{name}' successfully removed.")
+
+
+@envs_app.command(name="list")
+def envs_list():
+    """List installed qBraid environments."""
+    installed, aliases = installed_envs_data()
+
+    console = Console()
+
+    if len(installed) == 0:
+        console.print(
+            "No qBraid environments installed.\n\n"
+            + "Use 'qbraid envs create' to create a new environment.",
+            style="yellow",
+        )
+        return
+
+    alias_path_pairs = [(alias, installed[slug_name]) for alias, slug_name in aliases.items()]
+    sorted_alias_path_pairs = sorted(
+        alias_path_pairs,
+        key=lambda x: (x[0] != "default", str(x[1]).startswith(str(Path.home())), x[0]),
+    )
+
+    current_env_path = Path(sys.executable).parent.parent.parent
+
+    max_alias_length = (
+        max(len(str(alias)) for alias, envpath in sorted_alias_path_pairs)
+        if sorted_alias_path_pairs
+        else 0
+    )
+
+    print("# qbraid environments:")
+    print("#")
+    print("")
+
+    for alias, path in sorted_alias_path_pairs:
+        mark = "*" if path == current_env_path else " "
+        # Format each line with spacing based on the longest alias for alignment
+        line = f"{alias.ljust(max_alias_length+3)}{mark} {path}"  # fix the most optimal spacing
+        console.print(line)
+
+
+@envs_app.command(name="activate")
+def envs_activate(
+    name: str = typer.Argument(..., help="Name of the environment. Values from 'qbraid envs list'.")
+):
+    """Activate qBraid environment.
+
+    NOTE: Currently only works on qBraid Lab platform, and select few other OS types.
+    """
+    installed, aliases = installed_envs_data()
+    if name in aliases:
+        venv_path: Path = installed[aliases[name]] / "pyenv"
+    elif name in installed:
+        venv_path: Path = installed[name] / "pyenv"
+    else:
+        raise typer.BadParameter(f"Environment '{name}' not found.")
+
+    from .activate import activate_pyvenv
+
+    activate_pyvenv(venv_path)
+
+
+if __name__ == "__main__":
+    envs_app()

qbraid_cli/envs/create.py

@@ -0,0 +1,128 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module supporting 'qbraid envs create' command.
+
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from typing import Optional
+
+
+def replace_str(target: str, replacement: str, file_path: str) -> None:
+    """Replace all instances of string in file"""
+    with open(file_path, "r", encoding="utf-8") as file:
+        content = file.read()
+
+    content = content.replace(target, replacement)
+
+    with open(file_path, "w", encoding="utf-8") as file:
+        file.write(content)
+
+
+def update_state_json(
+    slug_path: str,
+    install_complete: int,
+    install_success: int,
+    message: Optional[str] = None,
+    env_name: Optional[str] = None,
+) -> None:
+    """Update environment's install status values in a JSON file.
+    Truth table values: 0 = False, 1 = True, -1 = Unknown
+    """
+    # Set default message if none provided
+    message = "" if message is None else message.replace("\n", " ")
+
+    # File path for state.json
+    state_json_path = os.path.join(slug_path, "state.json")
+
+    # Read existing data or use default structure
+    if os.path.exists(state_json_path):
+        with open(state_json_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    else:
+        data = {"install": {}}
+
+    # Update the data
+    data["install"]["complete"] = install_complete
+    data["install"]["success"] = install_success
+    data["install"]["message"] = message
+
+    if env_name is not None:
+        data["name"] = env_name
+
+    # Write updated data back to state.json
+    with open(state_json_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=4)
+
+
+def create_venv(slug_path: str, prompt: str) -> None:
+    """Create virtual environment and swap PS1 display name."""
+    venv_path = os.path.join(slug_path, "pyenv")
+    subprocess.run([sys.executable, "-m", "venv", venv_path], check=True)
+
+    # Determine the correct directory for activation scripts based on the operating system
+    if sys.platform == "win32":
+        scripts_path = os.path.join(venv_path, "Scripts")
+        activate_files = ["activate.bat", "Activate.ps1"]
+    else:
+        scripts_path = os.path.join(venv_path, "bin")
+        activate_files = ["activate", "activate.csh", "activate.fish"]
+
+    for file in activate_files:
+        file_path = os.path.join(scripts_path, file)
+        if os.path.isfile(file_path):
+            replace_str("(pyenv)", f"({prompt})", file_path)
+
+    replace_str(
+        "include-system-site-packages = false",
+        "include-system-site-packages = true",
+        os.path.join(venv_path, "pyvenv.cfg"),
+    )
+
+    update_state_json(slug_path, 1, 1)
+
+
+def create_qbraid_env_assets(slug: str, alias: str, kernel_name: str, slug_path: str) -> None:
+    """Create a qBraid environment including python venv, PS1 configs,
+    kernel resource files, and qBraid state.json."""
+    # pylint: disable-next=import-outside-toplevel
+    from jupyter_client.kernelspec import KernelSpecManager
+
+    local_resource_dir = os.path.join(slug_path, "kernels", f"python3_{slug}")
+    os.makedirs(local_resource_dir, exist_ok=True)
+
+    # create state.json
+    update_state_json(slug_path, 0, 0, env_name=alias)
+
+    # create kernel.json
+    kernel_json_path = os.path.join(local_resource_dir, "kernel.json")
+    kernel_spec_manager = KernelSpecManager()
+    kernelspec_dict = kernel_spec_manager.get_all_specs()
+    kernel_data = kernelspec_dict["python3"]["spec"]
+    if sys.platform == "win32":
+        python_exec_path = os.path.join(slug_path, "pyenv", "Scripts", "python.exe")
+    else:
+        python_exec_path = os.path.join(slug_path, "pyenv", "bin", "python")
+    kernel_data["argv"][0] = python_exec_path
+    kernel_data["display_name"] = kernel_name
+    with open(kernel_json_path, "w", encoding="utf-8") as file:
+        json.dump(kernel_data, file, indent=4)
+
+    # copy logo files
+    sys_resource_dir = kernelspec_dict["python3"]["resource_dir"]
+    logo_files = ["logo-32x32.png", "logo-64x64.png", "logo-svg.svg"]
+
+    for file in logo_files:
+        sys_path = os.path.join(sys_resource_dir, file)
+        loc_path = os.path.join(local_resource_dir, file)
+        if os.path.isfile(sys_path):
+            shutil.copy(sys_path, loc_path)
+
+    # create python venv
+    create_venv(slug_path, alias)

qbraid_cli/envs/data_handling.py

@@ -0,0 +1,140 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module for handling data related to qBraid environments.
+
+"""
+
+import json
+import keyword
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+import typer
+
+from qbraid_cli.handlers import QbraidException
+
+
+def is_valid_env_name(env_name: str) -> bool:  # pylint: disable=too-many-return-statements
+    """
+    Validates a Python virtual environment name against best practices.
+
+    This function checks if the given environment name is valid based on certain
+    criteria, including length, use of special characters, reserved names, and
+    operating system-specific restrictions.
+
+    Args:
+        env_name (str): The name of the Python virtual environment to validate.
+
+    Returns:
+        bool: True if the name is valid, False otherwise.
+
+    Raises:
+        ValueError: If the environment name is not a string or is empty.
+    """
+    # Basic checks for empty names or purely whitespace names
+    if not env_name or env_name.isspace():
+        return False
+
+    # Check for invalid characters, including shell metacharacters and spaces
+    if re.search(r'[<>:"/\\|?*\s&;()$[\]#~!{}]', env_name):
+        return False
+
+    if env_name.startswith("tmp"):
+        return False
+
+    # Reserved names for Windows (example list, can be expanded)
+    reserved_names = [
+        "CON",
+        "PRN",
+        "AUX",
+        "NUL",
+        "COM1",
+        "COM2",
+        "COM3",
+        "COM4",
+        "COM5",
+        "COM6",
+        "COM7",
+        "COM8",
+        "COM9",
+        "LPT1",
+        "LPT2",
+        "LPT3",
+        "LPT4",
+        "LPT5",
+        "LPT6",
+        "LPT7",
+        "LPT8",
+        "LPT9",
+    ]
+    if env_name.upper() in reserved_names:
+        return False
+
+    if len(env_name) > 20:
+        return False
+
+    # Check against Python reserved words
+    if keyword.iskeyword(env_name):
+        return False
+
+    # Check if it starts with a number, which is not a good practice
+    if env_name[0].isdigit():
+        return False
+
+    return True
+
+
+def validate_env_name(value: str) -> str:
+    """Validate environment name."""
+    if not is_valid_env_name(value):
+        raise typer.BadParameter(
+            f"Invalid environment name '{value}'. " "Please use a valid Python environment name."
+        )
+    return value
+
+
+def installed_envs_data() -> Tuple[Dict[str, Path], Dict[str, str]]:
+    """Gather paths and aliases for all installed qBraid environments."""
+    from qbraid_core.services.environments.paths import get_default_envs_paths, is_valid_slug
+
+    installed = {}
+    aliases = {}
+
+    qbraid_env_paths: List[Path] = get_default_envs_paths()
+
+    for env_path in qbraid_env_paths:
+        for entry in env_path.iterdir():
+            if entry.is_dir() and is_valid_slug(entry.name):
+                installed[entry.name] = entry
+
+                if entry.name == "qbraid_000000":
+                    aliases["default"] = entry.name
+                    continue
+
+                state_json_path = entry / "state.json"
+                if state_json_path.exists():
+                    try:
+                        with open(state_json_path, "r", encoding="utf-8") as f:
+                            data = json.load(f)
+                        aliases[data.get("name", entry.name[:-7])] = entry.name
+                    # pylint: disable-next=broad-exception-caught
+                    except (json.JSONDecodeError, Exception):
+                        aliases[entry.name[:-7]] = entry.name
+                else:
+                    aliases[entry.name[:-7]] = entry.name
+    return installed, aliases
+
+
+def request_delete_env(slug: str) -> str:
+    """Send request to delete environment given slug."""
+    from qbraid_core import QbraidSession, RequestsApiError
+
+    session = QbraidSession()
+
+    try:
+        session.delete(f"/environments/{slug}")
+    except RequestsApiError as err:
+        raise QbraidException("Delete environment request failed") from err

qbraid_cli/exceptions.py

@@ -1,12 +1,24 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
 """
-Module defining exceptions raised by the qBraid CLI.
+Module defining custom exceptions for the qBraid CLI.
 
 """
 
+from typing import Optional
+
+DEFAULT_ERROR_MESSAGE = (
+    "An unexpected error occurred while processing your qBraid CLI command. "
+    "Please check your input and try again. If the problem persists, "
+    "visit https://github.com/qBraid/qBraid-Lab/issues to file a bug report."
+)
 
-class QbraidCLIException(Exception):
-    """Base class for exceptions raised by the qBraid CLI."""
 
+class QbraidException(Exception):
+    """Custom exception class for qBraid CLI errors."""
 
-class QuantumJobsException(QbraidCLIException):
-    """Class for exceptions raised by qBraid Quantum Jobs."""
+    def __init__(self, message: Optional[str] = None):
+        if message is None:
+            message = DEFAULT_ERROR_MESSAGE
+        super().__init__(message)