weaverstack 0.1.1__py3-none-any.whl

weaver_cli/main.py

@@ -0,0 +1,626 @@
+"""Top-level CLI routing.
+
+Commands are registered here as the core APIs they wrap become available. The
+handler contract is the one convention worth keeping from the old repository:
+a command function returns a plain serialisable structure and the CLI prints
+it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+import weaver
+from weaver.errors import WeaverError
+
+#: The capacity verbs, kept here so the parser needs no Fabric import — a
+#: CLI-only install without the [fabric] extra must still build its parser.
+CAPACITY_ACTIONS = ("status", "resume", "suspend")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="weaver",
+        description="Weaver — build and load Fabric Lakehouse and Warehouse objects.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"weaverstack {weaver.__version__}",
+    )
+    subcommands = parser.add_subparsers(dest="command", metavar="command")
+
+    doctor = subcommands.add_parser(
+        "doctor", help="check whether this machine can run local Spark and Delta"
+    )
+    doctor.add_argument("--json", action="store_true", help="emit the report as JSON")
+    doctor.set_defaults(handler=handle_doctor)
+
+    build = subcommands.add_parser(
+        "build", help="build bound logical items from an explicit repository"
+    )
+    build.add_argument(
+        "repository",
+        nargs="?",
+        help="authored repository folder; defaults to the current directory/Notebook Resources",
+    )
+    build.add_argument(
+        "--bind",
+        dest="item_bindings",
+        action="append",
+        metavar="PHYSICAL[=LOGICAL]",
+        help="typed physical target with configured default or logical override",
+    )
+    build.add_argument(
+        "--bundle",
+        nargs="?",
+        const="",
+        metavar="NAME",
+        help=(
+            "optionally retain a .weaver.zip build record; omit NAME for a UTC "
+            "timestamp"
+        ),
+    )
+    build.add_argument("--json", action="store_true", help="emit the result as JSON")
+    _add_workspace_args(build)
+    build.set_defaults(handler=handle_build)
+
+    push = subcommands.add_parser(
+        "push", help="compatibility utility: validate and upload an authored repository"
+    )
+    push.add_argument("repository", help="local authored repository folder")
+    push.add_argument("--json", action="store_true", help="emit the result as JSON")
+    _add_workspace_args(push)
+    push.set_defaults(handler=handle_push)
+
+    unbind = subcommands.add_parser(
+        "unbind", help="remove catalogue state for named physical targets"
+    )
+    unbind.add_argument(
+        "targets",
+        nargs="+",
+        metavar="TARGET",
+        help="Lakehouse/Name or Warehouse/Name",
+    )
+    unbind.add_argument("--json", action="store_true", help="emit the result as JSON")
+    _add_workspace_args(unbind)
+    unbind.set_defaults(handler=handle_unbind)
+
+    wipe = subcommands.add_parser(
+        "wipe", help="clear a physical Lakehouse or Warehouse"
+    )
+    wipe.add_argument(
+        "targets",
+        nargs="+",
+        metavar="TARGET",
+        help="Lakehouse/Name[/Files|/Tables] or Warehouse/Name",
+    )
+    _add_workspace_args(wipe)
+    wipe.add_argument(
+        "--unbind-from",
+        metavar="LAKEHOUSE",
+        help="immediately remove wiped target claims from this Weaver catalogue",
+    )
+    wipe.add_argument("--dry-run", action="store_true", help="report without removing")
+    wipe.add_argument("--yes", action="store_true", help="do not ask for confirmation")
+    wipe.add_argument("--json", action="store_true", help="emit the result as JSON")
+    wipe.set_defaults(handler=handle_wipe)
+
+    install = subcommands.add_parser(
+        "install",
+        help="build Weaver and install it into a Fabric Environment",
+    )
+    _add_workspace_args(install, include_weaver_lakehouse=False)
+    install.add_argument(
+        "--no-publish",
+        action="store_true",
+        help="stage the wheel and dependencies but do not publish (development only)",
+    )
+    install.add_argument("--json", action="store_true", help="emit the result as JSON")
+    install.set_defaults(handler=handle_install)
+
+    notebook = subcommands.add_parser(
+        "notebook", help="deploy or execute a Fabric notebook"
+    )
+    notebook_commands = notebook.add_subparsers(
+        dest="notebook_command", metavar="command"
+    )
+
+    notebook_push = notebook_commands.add_parser(
+        "push", help="create or update a notebook definition"
+    )
+    notebook_push.add_argument("source", help="local .py or .ipynb notebook source")
+    notebook_push.add_argument("--name", help="Fabric display name; defaults to filename")
+    notebook_push.add_argument("--description")
+    notebook_push.add_argument("--json", action="store_true")
+    _add_workspace_args(notebook_push, include_weaver_lakehouse=False)
+    notebook_push.set_defaults(handler=handle_notebook_push)
+
+    notebook_run = notebook_commands.add_parser(
+        "run", help="execute a deployed notebook in Fabric"
+    )
+    notebook_run.add_argument("name", help="Fabric Notebook display name")
+    notebook_run.add_argument(
+        "--lakehouse",
+        help="default Lakehouse attached to the notebook session",
+    )
+    notebook_run.add_argument("--no-wait", action="store_true")
+    notebook_run.add_argument("--timeout", type=float, default=7200.0)
+    notebook_run.add_argument("--poll-interval", type=float, default=10.0)
+    notebook_run.add_argument("--json", action="store_true")
+    _add_workspace_args(notebook_run)
+    notebook_run.set_defaults(handler=handle_notebook_run)
+
+    capacity = subcommands.add_parser(
+        "capacity", help="turn a Fabric capacity on or off, or report its state"
+    )
+    capacity.add_argument("action", choices=CAPACITY_ACTIONS)
+    capacity.add_argument("--resource-group", required=True)
+    capacity.add_argument("--capacity-name", required=True)
+    capacity.add_argument(
+        "--subscription-id",
+        help="only needed when az has more than one subscription",
+    )
+    capacity.set_defaults(handler=handle_capacity)
+
+    return parser
+
+
+def _fabric_cli_workspace(args: argparse.Namespace):
+    """Resolve the Fabric-only values shared by notebook CLI utilities."""
+
+    from weaver.errors import CommandError
+    from weaver.workspaces import FabricWorkspace
+
+    workspace = _resolve_workspace(args)
+    if not isinstance(workspace, FabricWorkspace):
+        raise CommandError("weaver notebook requires a Fabric Workspace")
+    return workspace
+
+
+def handle_notebook_push(args: argparse.Namespace) -> int:
+    """Deploy a notebook definition without adding notebook APIs to core."""
+
+    import json
+
+    from weaver.fabric.notebooks import push_notebook
+
+    workspace = _fabric_cli_workspace(args)
+    result = push_notebook(
+        args.source,
+        workspace=workspace.workspace,
+        name=args.name,
+        description=args.description,
+    )
+    if args.json:
+        print(json.dumps(result.to_mapping(), indent=2))
+    else:
+        print(f"{result.action} notebook {result.notebook!r} in {result.workspace!r}")
+        print(f"  id:     {result.notebook_id}")
+        print(f"  source: {result.source}")
+    return 0
+
+
+def handle_notebook_run(args: argparse.Namespace) -> int:
+    """Run a notebook with explicit session attachments."""
+
+    import json
+
+    from weaver.errors import CommandError
+    from weaver.fabric.notebooks import run_notebook
+
+    workspace = _fabric_cli_workspace(args)
+    lakehouse = args.lakehouse or workspace.weaver_lakehouse
+    if not lakehouse:
+        raise CommandError(
+            "notebook run requires --lakehouse or a configured Weaver Lakehouse"
+        )
+    if not workspace.environment:
+        raise CommandError(
+            "notebook run requires --environment or a configured Environment"
+        )
+    result = run_notebook(
+        args.name,
+        workspace=workspace.workspace,
+        lakehouse=lakehouse,
+        environment=workspace.environment,
+        wait=not args.no_wait,
+        timeout=args.timeout,
+        poll_interval=args.poll_interval,
+    )
+    if args.json:
+        print(json.dumps(result.to_mapping(), indent=2))
+    else:
+        print(f"notebook {result.notebook!r}: {result.status}")
+        print(f"  job: {result.job_url}")
+        if result.exit_value is not None:
+            print(f"  result: {result.exit_value}")
+    return 0 if result.succeeded or args.no_wait else 1
+
+
+def handle_install(args: argparse.Namespace) -> int:
+    """Build Weaver from this checkout and install it into a Fabric Environment.
+
+    The authoritative deployment path. Afterwards a notebook, Livy session or
+    Fabric pytest run attached to the Environment can ``import weaver`` with no
+    source shipped into a Lakehouse.
+    """
+
+    from weaver.workspaces import FabricWorkspace
+    from weaver.errors import CommandError
+
+    workspace = _resolve_workspace(args)
+    if not isinstance(workspace, FabricWorkspace):
+        raise CommandError("weaver install requires a Fabric Workspace")
+    if not workspace.environment:
+        raise CommandError("weaver install requires --environment or a configured environment")
+    _prefer_desktop_credential()
+    from weaver.fabric import install as run_install
+
+    started = time.perf_counter()
+    result = run_install(
+        workspace.workspace,
+        workspace.environment,
+        publish=not args.no_publish,
+    )
+    total = time.perf_counter() - started
+
+    if args.json:
+        import json
+
+        payload = result.as_dict()
+        payload["timings"]["total"] = round(total, 2)
+        print(json.dumps(payload, indent=2))
+        return 0
+
+    _print_install(result, total)
+    return 0
+
+
+def _print_install(result, total: float) -> None:
+    print("Installed Weaver into Microsoft Fabric\n")
+    print("Workspace")
+    print(f"  Name: {result.workspace_name}")
+    print(f"  ID:   {result.workspace_id}\n")
+    print("Environment")
+    print(f"  Name: {result.environment_name}")
+    print(f"  ID:   {result.environment_id}\n")
+    print("Package")
+    print(f"  Distribution: {result.package_name}")
+    print(f"  Version:      {result.package_version}")
+    print(f"  Wheel:        {result.wheel_filename}\n")
+    print("Changes")
+    print(f"  Environment created:  {'yes' if result.created_environment else 'no'}")
+    print(f"  Dependencies changed: {'yes' if result.dependencies_changed else 'no'}")
+    print(f"  Wheel changed:        {'yes' if result.wheel_changed else 'no'}")
+    print(f"  Published:            {result.publish_status}\n")
+    parts = ", ".join(f"{name} {secs:.1f}s" for name, secs in result.timings.items())
+    print(f"Timing  {parts + ', ' if parts else ''}total {total:.1f}s\n")
+    print("Notebook use")
+    print(f'  1. Attach the "{result.environment_name}" Environment.')
+    print("  2. Start a new session.")
+    print("  3. Run: import weaver")
+
+
+def handle_capacity(args: argparse.Namespace) -> int:
+    """Report or change a capacity's state.
+
+    Capacity is billed while it runs, so this is the first and last thing a
+    Fabric session touches.
+    """
+
+    _prefer_desktop_credential()
+    from weaver.fabric import run_capacity_action
+
+    result = run_capacity_action(
+        args.action,
+        resource_group=args.resource_group,
+        capacity_name=args.capacity_name,
+        subscription_id=args.subscription_id,
+    )
+    print(result)
+    if args.action == "resume" and not result.running:
+        print("  (resuming takes a moment; run `capacity status` to confirm)")
+    return 0
+
+
+def _add_workspace_args(
+    parser: argparse.ArgumentParser, *, include_weaver_lakehouse: bool = True
+) -> None:
+    """Add the explicit values that a Workspace configuration can abbreviate."""
+
+    parser.add_argument("--workspace", help="Fabric Workspace name or local folder path")
+    parser.add_argument("--workspace-config", help="one Workspace configuration file")
+    parser.add_argument(
+        "--workspace-type",
+        choices=("fabric", "local"),
+        help="resource environment; defaults to fabric",
+    )
+    parser.add_argument("--environment", help="Fabric Environment name")
+    if include_weaver_lakehouse:
+        parser.add_argument("--weaver-lakehouse", help="control Lakehouse name")
+
+
+def _prefer_desktop_credential() -> None:
+    """Pin the Azure CLI credential for desktop commands.
+
+    Credential choice is the CLI's policy, not the core's. Best-effort — if the
+    Fabric extra is not installed there is nothing to pin, and a local command
+    never needs it.
+    """
+
+    try:
+        from weaver.fabric.auth import prefer_cli_credential
+    except ImportError:
+        return
+    prefer_cli_credential()
+
+
+def _desktop_store(workspace):
+    """The store a desktop command uses to reach a workspace.
+
+    Local is within-workspace; Fabric is cross-boundary, so the CLI constructs the
+    OneLakeDfsClient here — core never turns a FabricWorkspace into a DFS client.
+    """
+
+    from weaver.workspaces import LocalWorkspace
+    from weaver.store import LocalStore
+
+    if isinstance(workspace, LocalWorkspace):
+        return LocalStore()
+    from weaver.fabric import OneLakeDfsClient
+
+    return OneLakeDfsClient()
+
+
+def _resolve_workspace(args: argparse.Namespace):
+    from weaver.config import resolve_workspace
+    from weaver.workspaces import LocalWorkspace
+
+    workspace = resolve_workspace(
+        workspace=args.workspace,
+        workspace_type=args.workspace_type,
+        environment=args.environment,
+        weaver_lakehouse=getattr(args, "weaver_lakehouse", None),
+        workspace_config=args.workspace_config,
+    )
+
+    if not isinstance(workspace, LocalWorkspace):
+        _prefer_desktop_credential()
+    return workspace
+
+
+def handle_push(args: argparse.Namespace) -> int:
+    """Validate locally, then replace ``Files/weaver_items`` as one unit."""
+
+    import json
+
+    from weaver.locations import Location
+    from weaver.push import push_item_repository
+    from weaver.errors import CommandError
+    from weaver.resolution import resolver_for
+
+    workspace = _resolve_workspace(args)
+    if not workspace.weaver_lakehouse:
+        raise CommandError("push requires --weaver-lakehouse or a configured value")
+    resolver = resolver_for(workspace)
+    result = push_item_repository(
+        Location(args.repository),
+        resolver.weaver_items_root,
+        destination_store=_desktop_store(workspace),
+    )
+    payload = result.to_mapping()
+    if args.json:
+        print(json.dumps(payload, indent=2))
+    else:
+        print(f"pushed {len(result.files)} file(s)")
+        print(f"  from: {result.source}")
+        print(f"  to:   {result.destination}")
+        print(f"  signature: {result.repository_signature}")
+    return 0
+
+
+def handle_unbind(args: argparse.Namespace) -> int:
+    import json
+
+    from weaver.operations import _unbind_target_names
+    from weaver.errors import CommandError
+
+    lakehouses, warehouses = _unbind_target_names(args.targets)
+    workspace = _resolve_workspace(args)
+    if not workspace.weaver_lakehouse:
+        raise CommandError("unbind requires a configured Weaver Lakehouse")
+    result = _run_unbind(
+        workspace, lakehouses=lakehouses, warehouses=warehouses
+    )
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"unbound {len(result['logical_items'])} logical installation(s)")
+        for target in result["targets"]:
+            print(f"  {target}")
+    return 0
+
+
+def _run_unbind(workspace, *, lakehouses, warehouses) -> dict:
+    from weaver.workspaces import LocalWorkspace
+
+    if isinstance(workspace, LocalWorkspace):
+        from weaver.targets import ItemRef
+        from weaver.unbind import unbind_targets
+        from weaver.resolution import resolver_for
+        from weaver.spark import SparkCatalogue, local_delta_session
+
+        resolver = resolver_for(workspace)
+        with local_delta_session(workspace) as session:
+            catalogue = SparkCatalogue(
+                session,
+                resolver.spark_destination(ItemRef(workspace.weaver_lakehouse)),
+            )
+            return unbind_targets(
+                catalogue, lakehouses=lakehouses, warehouses=warehouses
+            ).to_mapping()
+
+    from weaver.fabric import LivySession
+
+    body = (
+        "from weaver.workspaces import FabricWorkspace\n"
+        "from weaver.targets import ItemRef\n"
+        "from weaver.unbind import unbind_targets\n"
+        "from weaver.resolution import resolver_for\n"
+        "from weaver.spark import SparkCatalogue\n"
+        f"workspace = FabricWorkspace(workspace={workspace.workspace!r}, "
+        f"environment={workspace.environment!r}, "
+        f"weaver_lakehouse={workspace.weaver_lakehouse!r})\n"
+        "resolver = resolver_for(workspace)\n"
+        "catalogue = SparkCatalogue(spark, resolver.spark_destination("
+        "ItemRef(workspace.weaver_lakehouse)))\n"
+        f"result = unbind_targets(catalogue, lakehouses={tuple(lakehouses)!r}, "
+        f"warehouses={tuple(warehouses)!r})\n"
+        "emit(result.to_mapping())\n"
+    )
+    with LivySession.for_workspace(workspace) as session:
+        return session.run(body).payload
+
+
+def handle_wipe(args: argparse.Namespace) -> int:
+    """Preview, confirm, then invoke the same public wipe operation."""
+
+    import json
+
+    workspace = _resolve_workspace(args)
+    planned = weaver.wipe(
+        args.targets,
+        workspace=workspace,
+        unbind_from=args.unbind_from,
+        dry_run=True,
+    )
+    print(f"wipe on {workspace.workspace}\n")
+    for report in planned.reports:
+        print(f"  {report.target}")
+        print(f"    {report.location}")
+        for name in report.removed:
+            print(f"      - {name}")
+        if not report.removed:
+            print("      (already empty)")
+    total = planned.count
+    print()
+
+    if args.dry_run:
+        if args.json:
+            print(json.dumps(planned.to_mapping(), indent=2))
+        else:
+            print(f"{total} item(s) would be removed. Nothing was changed.")
+        return 0
+
+    if total and not args.yes:
+        if not sys.stdin.isatty():
+            print(
+                f"Refusing to remove {total} item(s) without confirmation. "
+                "Pass --yes, or --dry-run to preview.",
+                file=sys.stderr,
+            )
+            return 1
+        answer = input(f"Remove {total} item(s)? This cannot be undone [y/N] ")
+        if answer.strip().lower() not in {"y", "yes"}:
+            print("Cancelled.")
+            return 1
+
+    result = weaver.wipe(
+        args.targets,
+        workspace=workspace,
+        unbind_from=args.unbind_from,
+    )
+    if args.json:
+        print(json.dumps(result.to_mapping(), indent=2))
+    elif result.count:
+        for report in result.reports:
+            print(f"  {report.target}: removed {report.count}")
+    else:
+        print("Nothing to remove.")
+    return 0
+
+
+def handle_build(args: argparse.Namespace) -> int:
+    """Adapt command-line values to :func:`weaver.build`."""
+
+    import json
+
+    workspace = _resolve_workspace(args)
+    result = weaver.build(
+        args.repository,
+        bind=args.item_bindings,
+        workspace=workspace,
+        bundle=args.bundle,
+    )
+    payload = result.to_mapping()
+    if args.json:
+        print(json.dumps(payload, indent=2))
+    else:
+        print(f"build {result.status}: workspace declaration")
+        print(f"  bundle: {result.bundle_id}")
+        if result.archive:
+            print(f"  record: {result.archive}")
+        print(f"  items:  {', '.join(result.items)}")
+        if result.errors:
+            for error in payload["errors"]:
+                print(f"  failed: {error['id']}: {error['type']}: {error['message']}")
+    return 0 if result.succeeded else 1
+
+
+def handle_doctor(args: argparse.Namespace) -> int:
+    """Report what a local build and load needs, and what is missing.
+
+    None of it is required to use Weaver on Fabric. It matters for local
+    development, where a missing JDK otherwise surfaces as a Java stack trace.
+    """
+
+    from weaver.diagnostics import check_local_spark, platform_summary
+
+    report = check_local_spark()
+
+    if args.json:
+        import json
+
+        print(json.dumps(report.as_dict(), indent=2))
+        return 0 if report.ok else 1
+
+    print(f"local Spark and Delta on {platform_summary()}\n")
+    for check in report.checks:
+        print(f"  {check}")
+    if report.ok:
+        print("\nReady. Run the local tests with:  pytest -m spark")
+        return 0
+    print()
+    for hint in report.hints:
+        print(f"  → {hint}")
+    # A non-zero status keeps this usable as a gate in a script, but on its own
+    # it reads as "your installation is broken" to someone who never wanted
+    # local Spark. Say plainly that it is optional.
+    print(
+        "\nThis reports local Spark only. Weaver on Fabric needs none of it —\n"
+        "wipe, install and capacity work without a JVM."
+    )
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help()
+        return 0
+
+    try:
+        return int(handler(args))
+    except WeaverError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())