divbase-cli 0.1.0a1__py3-none-any.whl

divbase_cli/cli_commands/version_cli.py

@@ -0,0 +1,214 @@
+"""CLI commands for managing project versions in DivBase."""
+
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+import typer
+from rich import print
+from rich.table import Table
+
+from divbase_cli.cli_commands.shared_args_options import FORMAT_AS_TSV_OPTION, PROJECT_NAME_OPTION
+from divbase_cli.config_resolver import ensure_logged_in, resolve_project
+from divbase_cli.services.project_versions import (
+    add_version_command,
+    delete_version_command,
+    get_version_details_command,
+    list_versions_command,
+    update_version_command,
+)
+from divbase_cli.utils import print_rich_table_as_tsv
+from divbase_lib.utils import format_file_size
+
+version_app = typer.Typer(
+    no_args_is_help=True,
+    help="Add, view and remove versions representing the state of all files in the entire project at the current timestamp.",
+)
+
+
+def format_timestamp(timestamp_str: str) -> str:
+    """Format ISO timestamp to Europe/Stockholm format with timezone"""
+    dt = datetime.fromisoformat(timestamp_str)
+    cet_dt = dt.astimezone(ZoneInfo("Europe/Stockholm"))
+    return cet_dt.strftime("%d/%m/%Y %H:%M:%S %Z")
+
+
+@version_app.command("add")
+def add_version(
+    name: str = typer.Argument(help="Name of the version (e.g., semantic version).", show_default=False),
+    description: str = typer.Option("", help="Optional description of the version."),
+    project: str | None = PROJECT_NAME_OPTION,
+):
+    """Add a new project version entry which specifies the current state of all files in the project at the current timestamp."""
+    project_config = resolve_project(project_name=project)
+    logged_in_url = ensure_logged_in(desired_url=project_config.divbase_url)
+
+    add_version_response = add_version_command(
+        name=name,
+        description=description,
+        project_name=project_config.name,
+        divbase_base_url=logged_in_url,
+    )
+    print(f"New version: '{add_version_response.name}' added to the project: '{project_config.name}'")
+
+
+@version_app.command("update")
+def update_version(
+    version_name: str = typer.Argument(help="Name of the existing version you want to modify", show_default=False),
+    new_name: str | None = typer.Option(
+        None, "--new-name", "-n", help="New name for the version. If not specified, the name will remain unchanged."
+    ),
+    new_description: str | None = typer.Option(
+        None,
+        "--new-description",
+        "-d",
+        help="Optional new description of the version. If not specified, the description will remain unchanged.",
+    ),
+    project: str | None = PROJECT_NAME_OPTION,
+):
+    """
+    Update an existing project version entry's name and/or description.
+
+    The files and timestamp associated with a version entry are immutable and cannot be changed.
+    This is by design to ensure version entries are representations of the project's state at the timepoint they were created at.
+    You can create a new version entry to capture the current state of the project instead.
+
+    To see your current version entries run: `divbase-cli version ls`
+    """
+    if not new_name and not new_description:
+        print(
+            "No updates specified. Please provide a new name (--new-name) and/or description (--new-description) to update for this entry."
+        )
+        return
+
+    project_config = resolve_project(project_name=project)
+    logged_in_url = ensure_logged_in(desired_url=project_config.divbase_url)
+
+    updated_version = update_version_command(
+        project_name=project_config.name,
+        divbase_base_url=logged_in_url,
+        version_name=version_name,
+        new_name=new_name,
+        new_description=new_description,
+    )
+    if new_name and new_name != version_name:
+        print(f"Version '{version_name}' renamed to '{updated_version.name}' in project: '{project_config.name}'")
+    else:
+        print(f"Version '{updated_version.name}' updated in project: '{project_config.name}'")
+    if new_description:
+        print(f"New description: '{updated_version.description}'")
+
+
+@version_app.command("ls")
+def list_versions(
+    project: str | None = PROJECT_NAME_OPTION,
+    include_deleted: bool = typer.Option(False, help="Include soft-deleted versions in the listing."),
+    format_output_as_tsv: bool = FORMAT_AS_TSV_OPTION,
+):
+    """
+    List all entries in the project versioning file.
+
+    Displays version name, creation timestamp, and description for each project version.
+    If you specify --include-deleted, soft-deleted versions will also be shown.
+    Soft-deleted versions can be restored by a DivBase admin within 30 days of deletion.
+    """
+    project_config = resolve_project(project_name=project)
+    logged_in_url = ensure_logged_in(desired_url=project_config.divbase_url)
+
+    versions_info = list_versions_command(
+        project_name=project_config.name, include_deleted=include_deleted, divbase_base_url=logged_in_url
+    )
+
+    if not versions_info:
+        print(f"No versions found for project: {project_config.name}.")
+        return
+
+    table = Table(title=f"Versions for {project_config.name}")
+    table.add_column("Version", style="cyan", no_wrap=True)
+    table.add_column("Created ", style="magenta")
+    table.add_column("Description", style="green")
+    if include_deleted:
+        table.add_column("Soft Deleted", style="red")
+
+    for version in versions_info:
+        name = version.name
+        desc = version.description or "No description provided"
+        created_at = format_timestamp(version.created_at)
+        if include_deleted:
+            soft_deleted = "Yes" if version.is_deleted else "No"
+            table.add_row(name, created_at, desc, soft_deleted)
+        else:
+            table.add_row(name, created_at, desc)
+
+    if not format_output_as_tsv:
+        print(table)
+    else:
+        print_rich_table_as_tsv(table=table)
+
+
+@version_app.command("info")
+def get_version_info(
+    version: str = typer.Argument(help="Specific version to retrieve information for"),
+    project: str | None = PROJECT_NAME_OPTION,
+    format_output_as_tsv: bool = FORMAT_AS_TSV_OPTION,
+):
+    """
+    Provide detailed information about a user specified project version, including all files present and their unique hashes.
+    """
+    project_config = resolve_project(project_name=project)
+    logged_in_url = ensure_logged_in(desired_url=project_config.divbase_url)
+
+    version_details = get_version_details_command(
+        project_name=project_config.name, divbase_base_url=logged_in_url, version_name=version
+    )
+
+    table = Table(title=f"Project version files for {project_config.name}")
+    table.add_column("Name", style="cyan", no_wrap=True)
+    table.add_column("Version ID", style="magenta")
+    table.add_column("MD5 Checksum", style="green")
+    table.add_column("Size", style="yellow")
+    for object_name, file_details in version_details.files.items():
+        file_size = format_file_size(file_details["size"])
+
+        table.add_row(
+            object_name,
+            file_details["version_id"],
+            file_details["etag"],
+            file_size,
+        )
+
+    if not format_output_as_tsv:
+        print(f"Project version entry for project: '{project_config.name}' with name: '{version_details.name}'")
+        print(f"Entry created at: {format_timestamp(version_details.created_at)}")
+        if version_details.description:
+            print(f"Description: {version_details.description}")
+        if version_details.is_deleted:
+            print(
+                "[red]WARNING: This version has been soft-deleted and will soon be permanently deleted unless restored - Contact a DivBase admin to prevent this.[/red]"
+            )
+        print(table)
+    else:
+        print_rich_table_as_tsv(table=table)
+
+
+@version_app.command("rm")
+def delete_version(
+    name: str = typer.Argument(help="Name of the version (e.g., semantic version).", show_default=False),
+    project: str | None = PROJECT_NAME_OPTION,
+):
+    """
+    Delete a version entry in the project versioning table. This does not delete the files themselves.
+
+    Deleted version entries older than 30 days will be permanently deleted.
+    You can ask a DivBase admin to restore a deleted version within that time period.
+    """
+    project_config = resolve_project(project_name=project)
+    logged_in_url = ensure_logged_in(desired_url=project_config.divbase_url)
+
+    deleted_version = delete_version_command(
+        project_name=project_config.name, divbase_base_url=logged_in_url, version_name=name
+    )
+    if deleted_version.already_deleted:
+        date_deleted = format_timestamp(deleted_version.date_deleted)
+        print(f"The version: '{deleted_version.name}' has already been soft-deleted on {date_deleted}.")
+    else:
+        print(f"The version: '{deleted_version.name}' was deleted from the project: '{project_config.name}'")

divbase_cli/cli_config.py

@@ -0,0 +1,71 @@
+"""
+Settings for DivBase CLI.
+
+This class creates a single 'settings' object at module load time that can be imported and used throughout the entire package.
+
+The user config and tokens are stored in the users local app dir:
+https://typer.tiangolo.com/tutorial/app-dir/
+"""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import typer
+from pydantic import SecretStr
+
+APP_NAME = "divbase-cli"
+APP_DIR = Path(typer.get_app_dir(APP_NAME))
+DEFAULT_METADATA_TSV_NAME = "sample_metadata.tsv"
+DEFAULT_LOG_LEVEL = "INFO"
+DEV_MODE = os.getenv("DIVBASE_DEV", "0") == "1"
+CONFIG_PATH = APP_DIR / "config.yaml"
+TOKENS_PATH = APP_DIR / ".secrets"
+
+if DEV_MODE:
+    DEFAULT_DIVBASE_API_URL = "http://localhost:8000/api"
+    DEFAULT_LOGGING_ON = "1"
+else:
+    DEFAULT_DIVBASE_API_URL = "https://divbase.scilifelab-2-prod.sys.kth.se/api"
+    DEFAULT_LOGGING_ON = "0"
+
+
+@dataclass
+class DivBaseCLISettings:
+    """
+    Settings for DivBase CLI.
+
+    You do not need to create an instance of this class yourself,
+    instead, import the 'cli_settings' instance created at this module's load time.
+    """
+
+    CONFIG_PATH: Path = Path(os.getenv("DIVBASE_CLI_CONFIG_PATH", CONFIG_PATH))
+
+    # for tokens stored via OS keyring, we use these to define a unique lookup key.
+    KEYRING_SERVICE: str = os.getenv("DIVBASE_KEYRING_SERVICE", "divbase-cli")
+    KEYRING_USERNAME: str = "tokens"
+    # Fallback path for tokens storage if keyring cannot be used on device.
+    TOKENS_PATH: Path = Path(os.getenv("DIVBASE_CLI_TOKENS_PATH", TOKENS_PATH))
+
+    DIVBASE_API_URL: str = os.getenv("DIVBASE_API_URL", DEFAULT_DIVBASE_API_URL)
+    METADATA_TSV_NAME: str = os.getenv("DIVBASE_METADATA_TSV_NAME", DEFAULT_METADATA_TSV_NAME)
+    LOGGING_ON: bool = os.getenv("DIVBASE_LOGGING_ON", DEFAULT_LOGGING_ON) == "1"
+    LOG_LEVEL: str = os.getenv("DIVBASE_LOG_LEVEL", DEFAULT_LOG_LEVEL).upper()
+
+    DIVBASE_API_PAT: SecretStr | None = field(init=False)
+
+    def __post_init__(self):
+        if os.getenv("DIVBASE_API_PAT"):
+            self.DIVBASE_API_PAT = SecretStr(os.environ["DIVBASE_API_PAT"])
+        else:
+            self.DIVBASE_API_PAT = None
+
+        valid_levels = ["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "NOTSET"]
+        if self.LOG_LEVEL not in valid_levels:
+            raise ValueError(f"Invalid LOG_LEVEL: {self.LOG_LEVEL}. Must be one of {valid_levels}.")
+
+        if self.DIVBASE_API_URL.endswith("/"):
+            self.DIVBASE_API_URL = self.DIVBASE_API_URL[:-1]
+
+
+cli_settings = DivBaseCLISettings()

divbase_cli/cli_exceptions.py

@@ -0,0 +1,166 @@
+"""
+Custom exceptions for the divbase CLI.
+"""
+
+from pathlib import Path
+
+from divbase_lib.divbase_constants import SUPPORTED_DIVBASE_FILE_TYPES, UNSUPPORTED_CHARACTERS_IN_FILENAMES
+
+
+class DivBaseCLIError(Exception):
+    """Base exception for all divbase CLI errors."""
+
+    pass
+
+
+class AuthenticationError(DivBaseCLIError):
+    """Raised for user authentication errors when using CLI tool."""
+
+    def __init__(self, error_message: str = "Authentication required, make sure you're logged in."):
+        super().__init__(error_message)
+
+
+class DivBaseAPIConnectionError(DivBaseCLIError):
+    """Raised when CLI tool can't connect to the provided DivBase API URL."""
+
+    def __init__(
+        self,
+        error_message: str = "Unable to connect to the DivBase API. Check the API URL and your network connection. Perhaps the server is down?",
+    ):
+        super().__init__(error_message)
+
+
+class DivBaseAPIError(DivBaseCLIError):
+    """
+    Used by CLI tool when making requests to DivBase API.
+    Raised when the DivBase API/server responds with an error status code.
+    Provides a helpful and easy-to-read error message for the user.
+    """
+
+    def __init__(
+        self,
+        error_details: str = "Not Provided",
+        error_type: str = "unknown",
+        status_code: int = 500,
+        http_method: str = "unknown",
+        url: str = "unknown",
+    ):
+        self.status_code = status_code
+        self.error_type = error_type
+        self.error_details = error_details
+        self.http_method = http_method
+        self.url = url
+        error_message = (
+            f"DivBase Server returned an error response:\n"
+            f"HTTP Status code: {status_code}\n"
+            f"HTTP method: {http_method}\n"
+            f"URL: {url}\n"
+            f"Error type: {error_type}\n"
+            f"Details: {error_details}\n"
+        )
+        self.error_message = error_message
+        super().__init__(error_message)
+
+
+class FileDoesNotExistInSpecifiedVersionError(DivBaseCLIError):
+    """Raised when a file does not exist in the project at the specified project version"""
+
+    def __init__(self, project_name: str, project_version: str, missing_files: list[str]):
+        missing_files_str = "\n".join(f"- '{name}'" for name in missing_files)
+        self.project_name = project_name
+        self.project_version = project_version
+        self.missing_files = missing_files
+
+        error_message = (
+            f"For the project: '{project_name}'\n"
+            f"And project version you specified: '{project_version}':\n"
+            "The following file(s) could not be found:\n"
+            f"{missing_files_str}"
+            "\n Maybe they only existed in a later version of the project?"
+        )
+        super().__init__(error_message)
+
+
+class FilesAlreadyInProjectError(DivBaseCLIError):
+    """
+    Raised when trying to upload file(s) that already exists in the project
+    and the user does not want to accidently create a new version of any file.
+    """
+
+    def __init__(self, existing_files: dict[Path, str], project_name: str):
+        files_list = "\n".join(
+            f"'{file_path}' (Checksum: {checksum})" for file_path, checksum in existing_files.items()
+        )
+        self.existing_files = existing_files
+        self.project_name = project_name
+
+        error_message = (
+            f"For the project: '{project_name}'\n"
+            "The exact version of the following file(s) that you're trying to upload already exist inside the project:\n"
+            f"{files_list}."
+        )
+        super().__init__(error_message)
+
+
+class ProjectNameNotSpecifiedError(DivBaseCLIError):
+    """
+    Raised when the project name is not specified in the command line arguments, and
+    no default project is set in the user config file.
+    """
+
+    def __init__(self):
+        error_message = (
+            "No project name provided.\n"
+            "Please either set a default project in your user configuration file.\n"
+            "or pass the flag '--project <project_name>' to this command.\n"
+            "To set a default project, you can run 'divbase-cli config set-default <project_name>'.\n"
+        )
+        super().__init__(error_message)
+
+
+class ProjectNotInConfigError(DivBaseCLIError):
+    """
+    Raised when the project name was
+        1. specified in the command line arguments OR
+        2. set as the default project in the user config file.
+    But info about the project could not be obtained from the user config file.
+    """
+
+    def __init__(self, config_path: Path, project_name: str):
+        self.config_path = config_path
+        self.project_name = project_name
+        error_message = (
+            f"Couldn't get information about the project named: '{project_name}' \n"
+            f"Please check the project is included in '{config_path.resolve()}'.\n"
+            f"you can run 'divbase-cli config show' to view the contents of your config file.\n"
+        )
+        super().__init__(error_message)
+
+
+class UnsupportedFileTypeError(DivBaseCLIError):
+    """Raised when one or more files to be uploaded are not supported by DivBase (based on file extension)."""
+
+    def __init__(self, unsupported_files: list[Path], supported_types: tuple[str, ...] = SUPPORTED_DIVBASE_FILE_TYPES):
+        self.unsupported_files = unsupported_files
+        self.supported_types = supported_types
+        message = (
+            f"The following file(s) have types that are not supported by DivBase and therefore cannot be uploaded: \n"
+            f"{'\n'.join(str(file) for file in unsupported_files)}\n"
+            f"DivBase currently supports the following file types: {', '.join(SUPPORTED_DIVBASE_FILE_TYPES)}\n"
+            "If you want us to support another file type, please let us know."
+        )
+        super().__init__(message)
+
+
+class UnsupportedFileNameError(DivBaseCLIError):
+    """Raised when one or more files to be uploaded have unsupported characters in their filenames."""
+
+    def __init__(self, unsupported_files: list[Path]):
+        self.unsupported_files = unsupported_files
+        message = (
+            f"The following file(s) have unsupported characters in their filenames and therefore cannot be uploaded: \n"
+            f"{'\n'.join(str(file) for file in unsupported_files)}\n"
+            f"Filenames cannot contain any of the following characters: {', '.join(UNSUPPORTED_CHARACTERS_IN_FILENAMES)}\n"
+            "Please rename the files and try again."
+        )
+        super().__init__(message)

divbase_cli/config_resolver.py

@@ -0,0 +1,86 @@
+"""
+Functions that resolve for the CLI commands things like:
+    - which project to use
+    - which download directory to use
+    - which DivBase API URL to use
+Based on provided user input and their config file.
+"""
+
+from pathlib import Path
+
+from divbase_cli.cli_config import cli_settings
+from divbase_cli.cli_exceptions import AuthenticationError, ProjectNameNotSpecifiedError
+from divbase_cli.user_config import ProjectConfig, load_user_config
+
+
+def ensure_logged_in(desired_url: str | None = None) -> str:
+    """
+    Ensure the user is logged in by checking the logged_in_url value in the user config.
+
+    Optionally checks the logged_in_url matches the desired_url (e.g. for project-specific commands) if provided.
+    """
+    config = load_user_config()
+    if config.logged_in_url:
+        if desired_url and config.logged_in_url != desired_url:
+            raise AuthenticationError(
+                f"You are not logged in to the correct DivBase URL: {desired_url}. Please log in again."
+            )
+        return config.logged_in_url
+
+    if cli_settings.DIVBASE_API_PAT:
+        return desired_url or cli_settings.DIVBASE_API_URL
+
+    raise AuthenticationError("You are not logged in. Please log in with 'divbase-cli auth login [EMAIL]'.")
+
+
+def resolve_url_for_non_project_specific_commands() -> str:
+    """
+    Resolve the DivBase API URL to use for CLI commands that are not project-specific.
+
+    Returns the url the user is either logged into or in the case of a user using a personal access token (PAT),
+    the default API URL, since PATs don't require login to be used.
+    Current examples: auth whoami and some task-history commands that are not project-specific.
+
+    Priority mirrors make_authenticated_request: active session first, PAT as fallback.
+    """
+    config = load_user_config()
+    if config.logged_in_url:
+        return config.logged_in_url
+
+    # No active session — fall back to PAT if available.
+    if cli_settings.DIVBASE_API_PAT:
+        return cli_settings.DIVBASE_API_URL
+
+    raise AuthenticationError("You are not logged in. Please log in with 'divbase-cli auth login [EMAIL]'.")
+
+
+def resolve_project(project_name: str | None) -> ProjectConfig:
+    """
+    Helper function to resolve the project to use for a CLI command.
+    Falls back to the default project set in the user config if not explicitly provided.
+
+    Once the project is resolved a ProjectConfig object is returned,
+    which contains the name and API URL of the project.
+    """
+    config = load_user_config()
+    if not project_name:
+        project_name = config.default_project
+    if not project_name:
+        raise ProjectNameNotSpecifiedError()
+    return config.project_info(project_name)
+
+
+def resolve_download_dir(download_dir: str | None) -> Path:
+    """
+    Helper function to resolve the download directory to use for a CLI command involving downloading files.
+
+    Priority given to `download_dir` argument, then if a default is set in the user config.
+    Note: "." or None should default to the current working directory.
+    """
+    if not download_dir:
+        config = load_user_config()
+        download_dir = config.default_download_dir
+
+    if download_dir and download_dir != ".":
+        return Path(download_dir)
+    return Path.cwd()