sleepybricks 1.0.0__py3-none-any.whl

sleepybricks/__init__.py

@@ -0,0 +1 @@
+"""sleepybricks: run databricks operations across multiple workspaces."""

sleepybricks/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for sleepybricks."""

sleepybricks/cli/commands/__init__.py

@@ -0,0 +1,49 @@
+"""Command registration helpers for sleepybricks."""
+
+from importlib import import_module
+from pathlib import Path
+from typing import Protocol, cast
+
+import typer
+
+
+class CommandModule(Protocol):
+    """Protocol describing a CLI command module."""
+
+    def register(self, app: typer.Typer) -> None:
+        """Register the module's command(s) with the root app."""
+
+
+def discoverCommandModules() -> list[CommandModule]:
+    """Import command modules in this package and return registrable ones.
+
+    Returns:
+        A list of imported command modules that expose a ``register`` function.
+    """
+
+    command_modules: list[CommandModule] = []
+    commands_dir = Path(__file__).resolve().parent
+
+    for module_path in sorted(commands_dir.glob("*.py")):
+        if module_path.stem == "__init__":
+            continue
+
+        module = import_module(f"{__name__}.{module_path.stem}")
+        if hasattr(module, "register"):
+            command_modules.append(cast(CommandModule, module))
+
+    return command_modules
+
+
+def registerCommands(app: typer.Typer) -> None:
+    """Register all command modules with the provided Typer app.
+
+    Args:
+        app: Root Typer application instance.
+
+    Returns:
+        None.
+    """
+
+    for command_module in discoverCommandModules():
+        command_module.register(app)

sleepybricks/cli/commands/dash_links.py

@@ -0,0 +1,87 @@
+"""``dash-links`` command: find dashboard links across workspaces."""
+
+from __future__ import annotations
+
+import typer
+
+from sleepybricks.cli.runtime import bootstrap
+from sleepybricks.core.workspace import getClient
+from sleepybricks.utils.formatting import renderTable
+
+
+def _buildLink(host: str, dashboard_id: str) -> str:
+    """Build the published link for a lakeview dashboard.
+
+    Args:
+        host: The workspace host URL.
+        dashboard_id: The dashboard id.
+
+    Returns:
+        The published dashboard URL.
+    """
+
+    return f"{host.rstrip('/')}/dashboardsv3/{dashboard_id}/published"
+
+
+def register(app: typer.Typer) -> None:
+    """Register the ``dash-links`` command.
+
+    Args:
+        app: Root Typer application instance.
+
+    Returns:
+        None.
+    """
+
+    @app.command("dash-links")
+    def dashLinks(
+        dashboard_name: str = typer.Argument(..., help="Case-sensitive dashboard name to match."),
+        profile_list: str = typer.Argument(
+            ..., help="Comma-separated profiles, e.g. 'dev,stg,us'."
+        ),
+    ) -> None:
+        """Fetch published links for a dashboard across one or more workspaces.
+
+        Dashboard names are not unique in databricks; the first match in each
+        workspace is used and a warning is shown when duplicates exist.
+
+        Args:
+            dashboard_name: Case-sensitive dashboard display name.
+            profile_list: Comma-separated list of profiles to search.
+
+        Returns:
+            None.
+        """
+
+        config, profiles = bootstrap(profile_list)
+
+        rows: list[list[str]] = []
+        for profile in profiles:
+            label = config.labelFor(profile)
+            try:
+                client = getClient(profile)
+                matches = [
+                    dashboard
+                    for dashboard in client.lakeview.list()
+                    if dashboard.display_name == dashboard_name
+                ]
+            except Exception as error:  # noqa: BLE001 - surface any SDK/auth error per profile
+                rows.append([label, f"⚠️ error: {error}"])
+                continue
+
+            if not matches:
+                rows.append([label, "(not found)"])
+                continue
+
+            if len(matches) > 1:
+                typer.secho(
+                    f"⚠️ {label}: found {len(matches)} dashboards named "
+                    f"'{dashboard_name}'; using the first.",
+                    fg=typer.colors.YELLOW,
+                )
+
+            first = matches[0]
+            rows.append([label, _buildLink(client.config.host, first.dashboard_id)])
+
+        typer.echo(f"\n✨ {dashboard_name} ✨\n")
+        typer.echo(renderTable(rows, headers=["Workspace", "Link"], table_style=config.table_style))

sleepybricks/cli/commands/pull.py

@@ -0,0 +1,91 @@
+"""``pull-repo`` command: pull the latest commit for a repo across workspaces."""
+
+from __future__ import annotations
+
+import typer
+from databricks.sdk import WorkspaceClient
+from databricks.sdk.service.workspace import RepoInfo
+
+from sleepybricks.cli.runtime import bootstrap
+from sleepybricks.core.workspace import getClient
+from sleepybricks.utils.formatting import renderTable
+
+
+def _findRepo(client: WorkspaceClient, repo_name: str) -> tuple[RepoInfo | None, int]:
+    """Find a repo by name within a workspace.
+
+    Args:
+        client: The workspace client to query.
+        repo_name: The repo name to match against repo paths.
+
+    Returns:
+        A tuple of the first matching repo (or ``None``) and the total match count.
+    """
+
+    matches = [repo for repo in client.repos.list() if repo_name in (repo.path or "")]
+    return (matches[0] if matches else None, len(matches))
+
+
+def register(app: typer.Typer) -> None:
+    """Register the ``pull-repo`` command.
+
+    Args:
+        app: Root Typer application instance.
+
+    Returns:
+        None.
+    """
+
+    @app.command("pull-repo")
+    def pullRepo(
+        repo_name: str = typer.Argument(..., help="Repo name to pull (matched within repo path)."),
+        profile_list: str = typer.Argument(
+            ..., help="Comma-separated profiles, e.g. 'dev,stg,us'."
+        ),
+    ) -> None:
+        """Pull the latest commit for a repo across one or more workspaces.
+
+        Args:
+            repo_name: The repo name to update.
+            profile_list: Comma-separated list of profiles.
+
+        Returns:
+            None.
+        """
+
+        config, profiles = bootstrap(profile_list)
+
+        rows: list[list[str]] = []
+        for profile in profiles:
+            label = config.labelFor(profile)
+            try:
+                client = getClient(profile)
+                repo, count = _findRepo(client, repo_name)
+                if repo is None:
+                    rows.append([label, repo_name, "-", "⚠️ not found (is it a git folder?)"])
+                    continue
+                if count > 1:
+                    typer.secho(
+                        f"⚠️ {label}: {count} repos match '{repo_name}'; using {repo.path}.",
+                        fg=typer.colors.YELLOW,
+                    )
+
+                if repo.branch:
+                    client.repos.update(repo.id, branch=repo.branch)
+                else:
+                    client.repos.update(repo.id)
+
+                updated = client.repos.get(repo.id)
+                head = (updated.head_commit_id or "")[:8] or "-"
+                rows.append([label, repo.path, updated.branch or "-", f"✅ pulled @ {head}"])
+            except Exception as error:  # noqa: BLE001 - surface any SDK/auth error per profile
+                rows.append([label, repo_name, "-", f"⚠️ error: {error}"])
+
+        typer.echo()
+        typer.echo(
+            renderTable(
+                rows,
+                headers=["Workspace", "Repo", "Branch", "Status"],
+                table_style=config.table_style,
+            )
+        )

sleepybricks/cli/commands/secrets.py

@@ -0,0 +1,164 @@
+"""``write-secret`` and ``create-scope`` commands for managing secrets."""
+
+from __future__ import annotations
+
+import typer
+from databricks.sdk import WorkspaceClient
+
+from sleepybricks.cli.runtime import bootstrap
+from sleepybricks.core.workspace import getClient
+from sleepybricks.utils.formatting import renderTable
+
+
+def _scopeExists(client: WorkspaceClient, scope_name: str) -> bool:
+    """Return whether a secret scope exists in the workspace.
+
+    Args:
+        client: The workspace client to query.
+        scope_name: The scope name to check.
+
+    Returns:
+        ``True`` when the scope is present.
+    """
+
+    return any(scope.name == scope_name for scope in client.secrets.list_scopes())
+
+
+def _parseWriteSecretArgs(parts: list[str]) -> tuple[str, str, str, str]:
+    """Parse the flexible ``write-secret`` positional arguments.
+
+    Supports both the four-arg form (``scope key value profiles``) and the
+    dotted three-arg form (``scope.key value profiles``).
+
+    Args:
+        parts: Raw positional arguments.
+
+    Returns:
+        A tuple of (scope, key, value, profile_list).
+
+    Raises:
+        typer.BadParameter: If the arguments don't match a supported form.
+    """
+
+    if len(parts) == 4:
+        scope, key, value, profile_list = parts
+        return scope, key, value, profile_list
+
+    if len(parts) == 3:
+        scoped_key, value, profile_list = parts
+        if "." not in scoped_key:
+            raise typer.BadParameter(
+                "Three-argument form expects '<scope>.<key>', e.g. 'my_scope.my_key'."
+            )
+        scope, key = scoped_key.split(".", 1)
+        if not scope or not key:
+            raise typer.BadParameter("Both scope and key are required in '<scope>.<key>'.")
+        return scope, key, value, profile_list
+
+    raise typer.BadParameter(
+        "Usage: write-secret <scope> <key> <value> <profiles>  |  "
+        "write-secret <scope>.<key> <value> <profiles>"
+    )
+
+
+def register(app: typer.Typer) -> None:
+    """Register the secret-management commands.
+
+    Args:
+        app: Root Typer application instance.
+
+    Returns:
+        None.
+    """
+
+    @app.command("write-secret")
+    def writeSecret(
+        parts: list[str] = typer.Argument(
+            ...,
+            help="<scope> <key> <value> <profiles>  OR  <scope>.<key> <value> <profiles>",
+        ),
+    ) -> None:
+        """Write a secret into a scope across one or more workspaces.
+
+        The scope must already exist; if it does not, the relevant
+        ``create-scope`` command is suggested.
+
+        Args:
+            parts: Positional arguments in one of the two supported forms.
+
+        Returns:
+            None.
+        """
+
+        scope_name, secret_key, secret_value, profile_list = _parseWriteSecretArgs(parts)
+        config, profiles = bootstrap(profile_list)
+
+        rows: list[list[str]] = []
+        for profile in profiles:
+            label = config.labelFor(profile)
+            try:
+                client = getClient(profile)
+                if not _scopeExists(client, scope_name):
+                    rows.append(
+                        [
+                            label,
+                            scope_name,
+                            secret_key,
+                            f"⚠️ scope missing — run: sleepybricks create-scope {scope_name} {profile}",
+                        ]
+                    )
+                    continue
+                client.secrets.put_secret(scope_name, secret_key, string_value=secret_value)
+                rows.append([label, scope_name, secret_key, "✅ written"])
+            except Exception as error:  # noqa: BLE001 - surface any SDK/auth error per profile
+                rows.append([label, scope_name, secret_key, f"⚠️ error: {error}"])
+
+        typer.echo()
+        typer.echo(
+            renderTable(
+                rows,
+                headers=["Workspace", "Scope", "Key", "Status"],
+                table_style=config.table_style,
+            )
+        )
+
+    @app.command("create-scope")
+    def createScope(
+        scope_name: str = typer.Argument(..., help="Name of the secret scope to create."),
+        profile_list: str = typer.Argument(
+            ..., help="Comma-separated profiles, e.g. 'dev,stg,us'."
+        ),
+    ) -> None:
+        """Create a secret scope across one or more workspaces.
+
+        Existing scopes are skipped and reported as already present.
+
+        Args:
+            scope_name: The scope name to create.
+            profile_list: Comma-separated list of profiles.
+
+        Returns:
+            None.
+        """
+
+        config, profiles = bootstrap(profile_list)
+
+        rows: list[list[str]] = []
+        for profile in profiles:
+            label = config.labelFor(profile)
+            try:
+                client = getClient(profile)
+                if _scopeExists(client, scope_name):
+                    rows.append([label, scope_name, "↩️ already existed"])
+                    continue
+                client.secrets.create_scope(scope_name)
+                rows.append([label, scope_name, "✅ created"])
+            except Exception as error:  # noqa: BLE001 - surface any SDK/auth error per profile
+                rows.append([label, scope_name, f"⚠️ error: {error}"])
+
+        typer.echo()
+        typer.echo(
+            renderTable(
+                rows, headers=["Workspace", "Scope", "Status"], table_style=config.table_style
+            )
+        )

sleepybricks/cli/commands/sql.py

@@ -0,0 +1,134 @@
+"""``sql`` command: run a SQL statement across workspaces."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from databricks.sdk.service.sql import StatementResponse, StatementState
+
+from sleepybricks.cli.runtime import bootstrap
+from sleepybricks.core.config import AppConfig
+from sleepybricks.core.workspace import findWarehouseId, getClient, runStatement
+from sleepybricks.utils.formatting import renderTable
+
+
+def _resolveStatement(sql_file: Optional[Path], sql_string: Optional[str]) -> str:
+    """Resolve the SQL text from the mutually-exclusive ``-f``/``-s`` options.
+
+    Args:
+        sql_file: Path to a ``.sql`` file, when provided.
+        sql_string: Literal SQL text, when provided.
+
+    Returns:
+        The SQL statement to execute.
+
+    Raises:
+        typer.BadParameter: If neither or both options are provided, or the file
+            is invalid.
+    """
+
+    if bool(sql_file) == bool(sql_string):
+        raise typer.BadParameter("Provide exactly one of -f/--file or -s/--string.")
+
+    if sql_string is not None:
+        return sql_string
+
+    assert sql_file is not None
+    if sql_file.suffix.lower() != ".sql":
+        raise typer.BadParameter(f"SQL file must have a .sql extension: {sql_file}")
+    if not sql_file.is_file():
+        raise typer.BadParameter(f"SQL file does not exist: {sql_file}")
+    return sql_file.read_text(encoding="utf-8")
+
+
+def _renderResult(response: StatementResponse, config: AppConfig) -> str:
+    """Render a statement response as text for a single workspace.
+
+    Args:
+        response: The terminal statement response.
+        config: Application configuration (for table style).
+
+    Returns:
+        Rendered output describing the result or failure.
+    """
+
+    state = response.status.state if response.status is not None else None
+
+    if state == StatementState.SUCCEEDED:
+        manifest = response.manifest
+        result = response.result
+        columns = (
+            [column.name for column in manifest.schema.columns]
+            if manifest is not None and manifest.schema is not None and manifest.schema.columns
+            else []
+        )
+        data = result.data_array if result is not None and result.data_array else []
+        if not data:
+            return "✅ succeeded (no rows returned)"
+        return renderTable(data, headers=columns, table_style=config.table_style)
+
+    if response.status is not None and response.status.error is not None:
+        return f"⚠️ {state}: {response.status.error.message}"
+    return f"⚠️ {state}"
+
+
+def register(app: typer.Typer) -> None:
+    """Register the ``sql`` command.
+
+    Args:
+        app: Root Typer application instance.
+
+    Returns:
+        None.
+    """
+
+    @app.command("sql")
+    def sql(
+        profile_list: str = typer.Argument(
+            ..., help="Comma-separated profiles, e.g. 'dev,stg,us'."
+        ),
+        sql_file: Optional[Path] = typer.Option(
+            None, "-f", "--file", help="Path to a .sql file to execute."
+        ),
+        sql_string: Optional[str] = typer.Option(
+            None, "-s", "--string", help="Literal SQL string to execute."
+        ),
+    ) -> None:
+        """Execute a SQL statement across one or more workspaces.
+
+        Requires a serverless SQL warehouse (resolved from the configured
+        ``serverless_warehouse_name``) in each target workspace.
+
+        Args:
+            profile_list: Comma-separated list of profiles to run against.
+            sql_file: Path to a ``.sql`` file (mutually exclusive with ``-s``).
+            sql_string: Literal SQL text (mutually exclusive with ``-f``).
+
+        Returns:
+            None.
+        """
+
+        config, profiles = bootstrap(profile_list)
+        statement = _resolveStatement(sql_file, sql_string)
+
+        for profile in profiles:
+            label = config.labelFor(profile)
+            typer.echo(f"\n─── {label} ───")
+            warehouse_name = config.warehouseNameFor(profile)
+            try:
+                client = getClient(profile)
+                warehouse_id = findWarehouseId(client, warehouse_name)
+                if warehouse_id is None:
+                    typer.secho(
+                        f"⚠️ serverless warehouse '{warehouse_name}' not found in this workspace.",
+                        fg=typer.colors.YELLOW,
+                    )
+                    continue
+                response = runStatement(client, statement, warehouse_id)
+            except Exception as error:  # noqa: BLE001 - surface any SDK/auth error per profile
+                typer.secho(f"⚠️ error: {error}", fg=typer.colors.YELLOW)
+                continue
+
+            typer.echo(_renderResult(response, config))

sleepybricks/cli/commands/workspace_folder.py

@@ -0,0 +1,80 @@
+"""``create-workspace-folder`` command: make a workspace folder everywhere."""
+
+from __future__ import annotations
+
+import typer
+from databricks.sdk.errors import NotFound
+
+from sleepybricks.cli.runtime import bootstrap
+from sleepybricks.core.workspace import getClient
+from sleepybricks.utils.formatting import renderTable
+
+
+def _normalizePath(folder_name: str) -> str:
+    """Normalize a folder name into an absolute workspace path.
+
+    Args:
+        folder_name: The folder name or path provided by the user.
+
+    Returns:
+        An absolute workspace path beginning with ``/``.
+    """
+
+    folder_name = folder_name.strip()
+    return folder_name if folder_name.startswith("/") else f"/{folder_name}"
+
+
+def register(app: typer.Typer) -> None:
+    """Register the ``create-workspace-folder`` command.
+
+    Args:
+        app: Root Typer application instance.
+
+    Returns:
+        None.
+    """
+
+    @app.command("create-workspace-folder")
+    def createWorkspaceFolder(
+        folder_name: str = typer.Argument(..., help="Folder path under the workspace root."),
+        profile_list: str = typer.Argument(
+            ..., help="Comma-separated profiles, e.g. 'dev,stg,us'."
+        ),
+    ) -> None:
+        """Create a workspace folder across one or more workspaces.
+
+        Existing folders are skipped and reported as already present.
+
+        Args:
+            folder_name: The folder path to create (``/`` prefixed if omitted).
+            profile_list: Comma-separated list of profiles.
+
+        Returns:
+            None.
+        """
+
+        config, profiles = bootstrap(profile_list)
+        path = _normalizePath(folder_name)
+
+        rows: list[list[str]] = []
+        for profile in profiles:
+            label = config.labelFor(profile)
+            try:
+                client = getClient(profile)
+                try:
+                    client.workspace.get_status(path)
+                    rows.append([label, path, "↩️ already existed"])
+                    continue
+                except NotFound:
+                    pass
+                client.workspace.mkdirs(path)
+                rows.append([label, path, "✅ created"])
+            except Exception as error:  # noqa: BLE001 - surface any SDK/auth error per profile
+                rows.append([label, path, f"⚠️ error: {error}"])
+
+        typer.echo()
+        typer.echo(
+            renderTable(
+                rows, headers=["Workspace", "Path", "Status"], table_style=config.table_style
+            )
+        )

sleepybricks/cli/runtime.py

@@ -0,0 +1,34 @@
+"""Shared runtime helpers for sleepybricks CLI commands.
+
+This module lives outside ``cli/commands`` so it is not picked up by the command
+auto-discovery in :mod:`sleepybricks.cli.commands`.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from sleepybricks.core.config import AppConfig, getConfig
+from sleepybricks.core.credentials import CredentialError, resolveProfiles
+
+
+def bootstrap(profile_list: str) -> tuple[AppConfig, list[str]]:
+    """Load config and resolve profiles, exiting gracefully on credential errors.
+
+    Args:
+        profile_list: A comma-separated string of profile names.
+
+    Returns:
+        A tuple of the application config and the validated profile names.
+
+    Raises:
+        typer.Exit: With code 1 when credentials cannot be resolved.
+    """
+
+    config = getConfig()
+    try:
+        profiles = resolveProfiles(profile_list)
+    except CredentialError as error:
+        typer.secho(str(error), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1) from error
+    return config, profiles

sleepybricks/core/__init__.py

@@ -0,0 +1 @@
+"""Core package for sleepybricks."""