playground-ls-cli 4.14.1.dev8__py3-none-any.whl

localstack_cli/pro/core/cli/state.py

@@ -0,0 +1,183 @@
+import json
+
+import click
+from localstack_cli.cli import console
+from localstack_cli.cli.exceptions import CLIError
+from localstack_cli.pro.core.bootstrap.pods_client import CloudPodsClient, StateService
+from localstack_cli.pro.core.cli.cli import RequiresLicenseGroup, _assert_host_reachable
+from localstack_cli.pro.core.cli.tree_view import TreeRenderer
+from localstack_cli.utils.analytics.cli import publish_invocation
+from localstack_cli.utils.collections import is_comma_delimited_list
+
+
+@click.group(
+    name="state",
+    short_help="(Preview) Export, restore, and reset LocalStack state.",
+    help="""
+    (Preview) Manage and manipulate the localstack state.
+
+    The state command group allows you to interact with LocalStack's state backend.
+
+    Read more: https://docs.localstack.cloud/references/persistence-mechanism/#snapshot-based-persistence
+    """,
+    cls=RequiresLicenseGroup,
+)
+def state() -> None:
+    pass
+
+
+@state.command(
+    name="reset",
+    short_help="Reset the state of LocalStack services",
+    help="""
+    Reset the service states of the current LocalStack runtime.
+
+    This command invokes a reset of services in the currently running LocalStack container.
+    By default, all services are rest. The `services` options allows to select a subset of services
+    which should be reset.
+
+    This command tries to automatically discover the running LocalStack instance.
+    If LocalStack has not been started with `localstack start` (and is not automatically discoverable),
+    please set `LOCALSTACK_HOST`.
+    """,
+)
+@click.option(
+    "-s",
+    "--services",
+    help="Comma-delimited list of services to reset. By default, the state of all running services is reset.",
+)
+@publish_invocation
+def reset(services: str | None) -> None:
+    from localstack_cli.pro.core.bootstrap import pods_client
+
+    if services and not is_comma_delimited_list(services):
+        raise click.ClickException("Input the services as a comma-delimited list")
+
+    service_list = [x.strip() for x in services.split(",")] if services else None
+    pods_client.reset_state(services=service_list)
+    console.print("LocalStack state successfully reset")
+
+
+@state.command(
+    name="export",
+    short_help="Export the state of LocalStack services",
+    help="""
+    Save the current state of the LocalStack container to a file on the local disk. This file can be restored at any
+    point in time using the `localstack state import` command. Please be aware that this might not be possible when
+    importing the state with a different version of LocalStack.
+
+    If you are looking for a managed solution to handle the state of your LocalStack container, please check out
+    the Cloud Pods feature: https://docs.localstack.cloud/user-guide/tools/cloud-pods/.
+
+    Use the DESTINATION argument to specify an absolute or relative path for the exported file.
+    If no destination is specified, a file named `ls-state-export` will be saved in the current working directory.
+
+    \b
+    Examples:
+        localstack state export my-state
+        localstack state export ../parent-dir/my-state
+        localstack state export /home/johndoe/my-state
+
+    You can also specify a subset of services to export with the `--services` option.
+
+    \b
+    For example:
+        localstack state export my-state --services s3,lambda
+
+    By default, the state of all running services is exported.
+    """,
+)
+@click.argument("destination", type=click.Path(resolve_path=True), default="ls-state-export")
+@click.option(
+    "-s",
+    "--services",
+    help="Comma-delimited list of services to reset. By default, the state of all running services is exported.",
+)
+@click.option(
+    "-f",
+    "--format",
+    "format_",
+    type=click.Choice(["json"]),
+    help="The formatting style for the save command output.",
+)
+@publish_invocation
+def export(destination: str, services: str | None = None, format_: str | None = None) -> None:
+    _assert_host_reachable()
+
+    client = StateService()
+    try:
+        services = [x.strip() for x in services.split(",") if x] if services else None
+        pod_info = client.export_pod(target=destination, services=services)
+        if format_ == "json":
+            console.print_json(json.dumps(pod_info))
+        else:
+            console.print(f"LocalStack state successfully exported to: {destination} ✅")
+        return
+    except Exception as e:
+        raise CLIError(f"Failed to export LocalStack state - {e}") from e
+
+
+@state.command(
+    name="import",
+    short_help="Import the state of LocalStack services",
+    help="""
+    Load the state of LocalStack from a file into the running container.
+    The SOURCE argument is the absolute or relative path to the file containing the state to import.
+    This file must have been generated from a previous `localstack state export` command.
+    Please be aware that it might not be possible to import a state generated from a different version of LocalStack.
+
+    \b
+    Examples:
+        localstack state import my-state
+        localstack state import ../parent-dir/my-state
+        localstack state import /home/johndoe/my-state
+    """,
+)
+@click.argument("source", type=click.Path(exists=True, resolve_path=True))
+@publish_invocation
+def import_state(source: str) -> None:
+    _assert_host_reachable()
+
+    client = StateService()
+    try:
+        client.import_pod(source=source, show_progress=True)
+        console.print(f"LocalStack state successfully imported from {source} ✅")
+    except Exception as e:
+        raise CLIError(f"Failed to import LocalStack state - {e}") from e
+
+
+@state.command(
+    name="inspect",
+    short_help="Inspect the state of LocalStack services",
+    help="""
+    Inspect the state of the Localstack Container.
+
+    By default, it starts a curses interface which allows an interactive inspection of the contents of the LocalStack
+    running instance.
+    """,
+)
+@click.option(
+    "-f",
+    "--format",
+    "format_",
+    type=click.Choice(["curses", "rich", "json"]),
+    default="curses",
+    help="The formatting style for the inspect command output.",
+)
+@publish_invocation
+def inspect_state(format_: str) -> None:
+    _assert_host_reachable()
+
+    client = CloudPodsClient()
+    try:
+        result = client.get_state_data()
+    except Exception:
+        raise CLIError("Error occurred while fetching the metamodel")
+
+    # filter out too noisy/verbose services like CloudWatch
+    skipped_services = ["cloudwatch"]
+    for account, details in result.items():
+        result[account] = {k: v for k, v in details.items() if k not in skipped_services}
+
+    # render tree with given format
+    TreeRenderer.get(format_).render_tree(result, "LocalStack State")

localstack_cli/pro/core/cli/tree_view.py

@@ -0,0 +1,235 @@
+"""Utilities to display trees in the terminal (e.g., interactive using `curses`, via `rich`, or as JSON)"""
+
+import functools
+import json
+import logging
+import os
+from abc import ABC
+from typing import Any
+
+from localstack_cli.utils.objects import SubtypesInstanceManager
+
+# constants
+ESC = 27
+INDENTATION = 2
+
+
+class TreeRenderer(SubtypesInstanceManager, ABC):
+    """Abstract base class for rendering trees (e.g., cloud pod contents) on the terminal."""
+
+    def render_tree(self, tree: dict[str, Any], tree_name: str):
+        raise NotImplementedError
+
+
+class TreeRendererRich(TreeRenderer):
+    @staticmethod
+    def impl_name() -> str:
+        return "rich"
+
+    def render_tree(self, tree: dict[str, Any], tree_name: str):
+        from rich import print
+        from rich.tree import Tree
+
+        def _convert(obj, parent):
+            if isinstance(obj, list):
+                for idx, o in enumerate(obj):
+                    subtree = Tree(str(idx))
+                    parent.add(_convert(o, subtree))
+                return parent
+            elif isinstance(obj, dict):
+                for k, v in obj.items():
+                    if isinstance(v, (dict, list)):
+                        if not v:
+                            return Tree(f"{k} = {v}")
+                        subtree = Tree(str(k))
+                        _convert(v, subtree)
+                        parent.add(subtree)
+                    else:
+                        parent.add(Tree(f"{k} = {v}"))
+                return parent
+            return Tree(str(obj))
+
+        tree_obj = Tree(tree_name)
+        _convert(tree, tree_obj)
+        print(tree_obj)
+
+
+class Tree:
+    def __init__(self, name, obj):
+        self.name = name
+        self.object = obj
+        self.expanded = True
+
+    def render(self, depth, width):
+        padding = " " * INDENTATION * depth
+        return self.pad(f"{padding}{self.icon()} {self.name}", width)
+
+    @functools.cache
+    def children(self):
+        def _name(key, value):
+            if isinstance(value, (list, dict)):
+                return key
+            return f"{value}" if isinstance(key, int) else f"{key} = {value}"
+
+        if isinstance(self.object, dict):
+            return [Tree(_name(k, v), v) for k, v in self.object.items()]
+        if isinstance(self.object, list):
+            return [Tree(_name(idx, v), v) for idx, v in enumerate(self.object)]
+        return []
+
+    def icon(self):
+        if self.children() and not self.expanded:
+            return "+"
+        return "-"
+
+    def expand(self):
+        self.expanded = True
+
+    def collapse(self):
+        self.expanded = False
+
+    def toggle(self):
+        self.expanded = not self.expanded
+
+    def traverse(self):
+        yield self, 0
+        if not self.expanded:
+            return
+        for _child in self.children():
+            for child, depth in _child.traverse():
+                yield child, depth + 1
+
+    def pad(self, data, width):
+        return data + " " * (width - len(data))
+
+
+class TreeRendererCurses(TreeRenderer):
+    """
+    Renders an interactive tree in the terminal via the curses library.
+    Loosely based on https://github.com/mcchae/treesel
+    """
+
+    # file logger, lazily initialized
+    LOG = None
+
+    @staticmethod
+    def impl_name() -> str:
+        return "curses"
+
+    def render_tree(self, dict_obj: dict, tree_name: str):
+        from curses import wrapper  # note: keep here to avoid import issues on some systems
+
+        saved_fds = (os.dup(0), os.dup(1))
+
+        def curses_main_wrapper(_tree: Tree):
+            def _main(win):
+                return self.curses_main(win, _tree)
+
+            return _main
+
+        try:
+            saved_fds = self.open_tty()
+            tree = Tree(tree_name, dict_obj)
+            wrapper(curses_main_wrapper(tree))
+        finally:
+            os.close(0)
+            os.close(1)
+            os.dup(saved_fds[0])
+            os.dup(saved_fds[1])
+
+    @staticmethod
+    def curses_main(win, tree: Tree):
+        """
+        Curses main loop that performs the rendering.
+        :param win: the `curses.window` instance to render on
+        :param tree: the tree structure to render
+        """
+        import curses  # note: keep here to avoid import issues on some systems
+
+        # initialize window
+        win.clear()
+        win.refresh()
+        curses.nl()
+        curses.noecho()
+        win.timeout(0)
+        win.nodelay(False)
+        tree.expand()
+        selected_line = 3
+        pending_action = None
+
+        # set up default terminal colors
+        curses.use_default_colors()
+
+        # main render loop
+        while True:
+            win.clear()
+            curses.init_pair(1, curses.COLOR_WHITE, curses.COLOR_BLUE)
+            line = 0
+            offset = max(0, selected_line - curses.LINES + 3)
+            for data, depth in tree.traverse():
+                if line == selected_line:
+                    win.attrset(curses.color_pair(1) | curses.A_BOLD)
+                    if pending_action:
+                        getattr(data, pending_action)()
+                        pending_action = None
+                else:
+                    win.attrset(curses.color_pair(0))
+                if 0 <= line - offset < curses.LINES - 1:
+                    win.addstr(line - offset, 0, data.render(depth, curses.COLS))
+                line += 1
+            win.refresh()
+            ch = win.getch()
+            if ch == curses.KEY_UP:
+                selected_line -= 1
+            elif ch == curses.KEY_DOWN:
+                selected_line += 1
+            elif ch == curses.KEY_PPAGE:
+                selected_line -= curses.LINES
+                if selected_line < 0:
+                    selected_line = 0
+            elif ch == curses.KEY_NPAGE:
+                selected_line += curses.LINES
+                if selected_line >= line:
+                    selected_line = line - 1
+            elif ch == curses.KEY_RIGHT:
+                pending_action = "expand"
+            elif ch == curses.KEY_LEFT:
+                pending_action = "collapse"
+            elif ch == ord(" "):
+                pending_action = "toggle"
+            elif ch == ESC:
+                return
+
+            selected_line %= line
+
+    @staticmethod
+    def open_tty():
+        saved_stdin = os.dup(0)
+        saved_stdout = os.dup(1)
+        os.close(0)
+        os.close(1)
+        os.open("/dev/tty", os.O_RDONLY)
+        os.open("/dev/tty", os.O_RDWR)
+        return saved_stdin, saved_stdout
+
+    @classmethod
+    def log(cls, *args, **kwargs):
+        """Logger that can be used to log debug output from curses program"""
+        if cls.LOG:
+            LOG = logging.getLogger(__file__)
+            handler = logging.FileHandler("cloud_pods_viewer.log")
+            formatter = logging.Formatter("%(asctime)s %(levelname)s %(message)s")
+            handler.setFormatter(formatter)
+            LOG.addHandler(handler)
+            LOG.setLevel(logging.INFO)
+        cls.LOG.info(*args, **kwargs)
+
+
+class TreeRendererJSON(TreeRenderer):
+    @staticmethod
+    def impl_name() -> str:
+        return "json"
+
+    def render_tree(self, dict_obj: dict, tree_name: str):
+        # simply print out the JSON with indentation
+        print(json.dumps(dict_obj, indent=4))