beaver-db 2.0rc2__py3-none-any.whl

beaver/cli/dicts.py

@@ -0,0 +1,171 @@
+import json
+import typer
+import rich
+from typing_extensions import Annotated
+from typing import Optional
+
+from beaver import BeaverDB
+
+app = typer.Typer(
+    name="dict",
+    help="Interact with namespaced dictionaries. (e.g., beaver dict my-dict get my-key)",
+)
+
+
+def _parse_value(value: str):
+    """Parses the value string as JSON if appropriate."""
+    if value.startswith("{") or value.startswith("["):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return value
+    return value
+
+
+@app.callback(invoke_without_command=True)
+def dict_main(
+    ctx: typer.Context,
+    name: Annotated[
+        Optional[str],
+        typer.Argument(help="The name of the dictionary to interact with."),
+    ] = None,
+):
+    """
+    Manage namespaced dictionaries.
+
+    If no name is provided, lists all available dictionaries.
+    """
+    db = ctx.obj["db"]
+
+    if db is None:
+        rich.print(f"[bold red]Database not found![/]")
+        return
+
+    if name is None:
+        # No name given, so list all dicts
+        rich.print("[bold]Available Dictionaries:[/bold]")
+        try:
+            dict_names = db.dicts
+            if not dict_names:
+                rich.print("  (No dictionaries found)")
+            else:
+                for dict_name in dict_names:
+                    rich.print(f"  • {dict_name}")
+            rich.print(
+                "\n[bold]Usage:[/bold] beaver dict [bold]<NAME>[/bold] [COMMAND]"
+            )
+            return
+        except Exception as e:
+            rich.print(f"[bold red]Error querying dictionaries:[/] {e}")
+            raise typer.Exit(code=1)
+
+    # A name was provided, store it in the context for subcommands
+    ctx.obj = {"name": name, "db": db}
+
+    if ctx.invoked_subcommand is None:
+        # A name was given, but no command (e.g., "beaver dict my-dict")
+        rich.print(f"No command specified for dictionary '[bold]{name}[/bold]'.")
+        rich.print("\n[bold]Commands:[/bold]")
+        rich.print("  get, set, del, keys, dump")
+        rich.print(
+            f"\nRun [bold]beaver dict {name} --help[/bold] for command-specific options."
+        )
+        raise typer.Exit()
+
+
+@app.command()
+def get(
+    ctx: typer.Context, key: Annotated[str, typer.Argument(help="The key to retrieve.")]
+):
+    """
+    Get a value by key.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        value = db.dict(name).get(key)
+        if value is None:
+            rich.print(f"[bold red]Error:[/] Key not found: '{key}'")
+            raise typer.Exit(code=1)
+
+        if isinstance(value, (dict, list)):
+            rich.print_json(data=value)
+        else:
+            rich.print(value)
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def set(
+    ctx: typer.Context,
+    key: Annotated[str, typer.Argument(help="The key to set.")],
+    value: Annotated[str, typer.Argument(help="The value (JSON or string).")],
+):
+    """
+    Set a value for a key.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        parsed_value = _parse_value(value)
+        db.dict(name)[key] = parsed_value
+        rich.print(f"[green]Success:[/] Key '{key}' set in dictionary '{name}'.")
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="del")
+def delete(
+    ctx: typer.Context, key: Annotated[str, typer.Argument(help="The key to delete.")]
+):
+    """
+    Delete a key from the dictionary.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        del db.dict(name)[key]
+        rich.print(f"[green]Success:[/] Key '{key}' deleted from dictionary '{name}'.")
+    except KeyError:
+        rich.print(f"[bold red]Error:[/] Key not found: '{key}'")
+        raise typer.Exit(code=1)
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def keys(ctx: typer.Context):
+    """
+    List all keys in the dictionary.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        all_keys = list(db.dict(name).keys())
+        if not all_keys:
+            rich.print(f"Dictionary '{name}' is empty.")
+            return
+        for key in all_keys:
+            rich.print(key)
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def dump(ctx: typer.Context):
+    """
+    Dump the entire dictionary as JSON.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        dump_data = db.dict(name).dump()
+        rich.print_json(data=dump_data)
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)

beaver/cli/lists.py

@@ -0,0 +1,244 @@
+import json
+import typer
+import rich
+import rich.table
+from typing_extensions import Annotated
+from typing import Optional
+
+from beaver import BeaverDB
+
+app = typer.Typer(
+    name="list",
+    help="Interact with persistent lists. (e.g., beaver list my-list push 'new item')",
+)
+
+
+def _get_db(ctx: typer.Context) -> BeaverDB:
+    """Helper to get the DB instance from the main context."""
+    return ctx.find_object(dict)["db"]
+
+
+def _parse_value(value: str):
+    """Parses the value string as JSON if appropriate."""
+    if value.startswith("{") or value.startswith("["):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            return value
+    return value
+
+
+@app.callback(invoke_without_command=True)
+def list_main(
+    ctx: typer.Context,
+    name: Annotated[
+        Optional[str], typer.Argument(help="The name of the list to interact with.")
+    ] = None,
+):
+    """
+    Manage persistent lists.
+
+    If no name is provided, lists all available lists.
+    """
+    db = _get_db(ctx)
+
+    if name is None:
+        # No name given, so list all lists
+        rich.print("[bold]Available Lists:[/bold]")
+        try:
+            list_names = db.lists
+            if not list_names:
+                rich.print("  (No lists found)")
+            else:
+                for list_name in list_names:
+                    rich.print(f"  • {list_name}")
+            rich.print(
+                "\n[bold]Usage:[/bold] beaver list [bold]<NAME>[/bold] [COMMAND]"
+            )
+            return
+        except Exception as e:
+            rich.print(f"[bold red]Error querying lists:[/] {e}")
+            raise typer.Exit(code=1)
+
+    # A name was provided, store it in the context for subcommands
+    ctx.obj = {"name": name, "db": db}
+
+    if ctx.invoked_subcommand is None:
+        # A name was given, but no command
+        try:
+            count = len(db.list(name))
+            rich.print(f"List '[bold]{name}[/bold]' contains {count} items.")
+            rich.print("\n[bold]Commands:[/bold]")
+            rich.print("  push, pop, deque, insert, remove, items, dump")
+            rich.print(
+                f"\nRun [bold]beaver list {name} --help[/bold] for command-specific options."
+            )
+        except Exception as e:
+            rich.print(f"[bold red]Error:[/] {e}")
+            raise typer.Exit(code=1)
+        raise typer.Exit()
+
+
+@app.command()
+def push(
+    ctx: typer.Context,
+    value: Annotated[str, typer.Argument(help="The value to add (JSON or string).")],
+):
+    """
+    Add (push) an item to the end of the list.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        parsed_value = _parse_value(value)
+        db.list(name).push(parsed_value)
+        rich.print(f"[green]Success:[/] Item pushed to list '{name}'.")
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def pop(ctx: typer.Context):
+    """
+    Remove and return the last item from the list.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        item = db.list(name).pop()
+        if item is None:
+            rich.print(f"List '{name}' is empty.")
+            return
+
+        rich.print("[green]Popped item:[/green]")
+        if isinstance(item, (dict, list)):
+            rich.print_json(data=item)
+        else:
+            rich.print(item)
+
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def deque(ctx: typer.Context):
+    """
+    Remove and return the first item from the list.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        item = db.list(name).deque()
+        if item is None:
+            rich.print(f"List '{name}' is empty.")
+            return
+
+        rich.print("[green]Dequeued item:[/green]")
+        if isinstance(item, (dict, list)):
+            rich.print_json(data=item)
+        else:
+            rich.print(item)
+
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def insert(
+    ctx: typer.Context,
+    index: Annotated[
+        int, typer.Argument(help="The index to insert at (e.g., 0 for front).")
+    ],
+    value: Annotated[str, typer.Argument(help="The value to insert (JSON or string).")],
+):
+    """
+    Insert an item at a specific index.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        parsed_value = _parse_value(value)
+        db.list(name).insert(index, parsed_value)
+        rich.print(
+            f"[green]Success:[/] Item inserted at index {index} in list '{name}'."
+        )
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def remove(
+    ctx: typer.Context,
+    index: Annotated[int, typer.Argument(help="The index of the item to remove.")],
+):
+    """
+    Remove and return an item from a specific index.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        # Get the item before deleting it to print it
+        item = db.list(name)[index]
+        del db.list(name)[index]
+
+        rich.print(f"[green]Success:[/] Removed item from index {index}:")
+        if isinstance(item, (dict, list)):
+            rich.print_json(data=item)
+        else:
+            rich.print(item)
+
+    except IndexError:
+        rich.print(f"[bold red]Error:[/] Index {index} out of range for list '{name}'.")
+        raise typer.Exit(code=1)
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def items(ctx: typer.Context):
+    """
+    Print all items in the list, in order.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        # `[:]` is the slice syntax to get all items from ListManager
+        all_items = db.list(name)[:]
+        if not all_items:
+            rich.print(f"List '{name}' is empty.")
+            return
+
+        table = rich.table.Table(title=f"Items in List: [bold]{name}[/bold]")
+        table.add_column("Index", style="cyan", justify="right")
+        table.add_column("Value")
+
+        for i, item in enumerate(all_items):
+            if isinstance(item, (dict, list)):
+                table.add_row(str(i), json.dumps(item))
+            else:
+                table.add_row(str(i), str(item))
+        rich.print(table)
+
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def dump(ctx: typer.Context):
+    """
+    Dump the entire list as JSON.
+    """
+    db = ctx.obj["db"]
+    name = ctx.obj["name"]
+    try:
+        dump_data = db.list(name).dump()
+        rich.print_json(data=dump_data)
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)

beaver/cli/locks.py

@@ -0,0 +1,202 @@
+import typer
+import rich
+import subprocess
+import threading
+from typing_extensions import Annotated
+from typing import Optional, List
+
+from beaver import BeaverDB
+from beaver.locks import LockManager
+
+app = typer.Typer(
+    name="lock",
+    help="Run commands under lock or manage locks. (e.g., beaver lock my-lock run bash -c 'sleep 10')",
+)
+
+
+def _get_db(ctx: typer.Context) -> BeaverDB:
+    """Helper to get the DB instance from the main context."""
+    return ctx.find_object(dict)["db"]
+
+
+@app.callback(invoke_without_command=True)
+def lock_main(
+    ctx: typer.Context,
+    name: Annotated[
+        Optional[str], typer.Argument(help="The unique name of the lock.")
+    ] = None,
+):
+    """
+    Manage and run commands under distributed locks.
+
+    If no name is provided, lists all active locks.
+    """
+    db = _get_db(ctx)
+
+    if name is None:
+        # No name given, so list all active locks
+        rich.print("[bold]Active Locks:[/bold]")
+        try:
+            lock_names = db.locks
+            if not lock_names:
+                rich.print("  (No active locks found)")
+            else:
+                for lock_name in lock_names:
+                    rich.print(f"  • {lock_name}")
+            rich.print(
+                "\n[bold]Usage:[/bold] beaver lock [bold]<LOCK_NAME>[/bold] [COMMAND]"
+            )
+            return
+        except Exception as e:
+            rich.print(f"[bold red]Error querying locks:[/] {e}")
+            raise typer.Exit(code=1)
+
+    # A name was provided, store it in the context for subcommands
+    ctx.obj = {"name": name, "db": db}
+
+    if ctx.invoked_subcommand is None:
+        # A name was given, but no command
+        rich.print(f"Lock '[bold]{name}[/bold]'.")
+        rich.print("\n[bold]Commands:[/bold]")
+        rich.print("  run, clear")
+        rich.print(
+            f"\nRun [bold]beaver lock {name} --help[/bold] for command-specific options."
+        )
+        raise typer.Exit()
+
+
+def _heartbeat_task(lock: LockManager, ttl: float, stop_event: threading.Event):
+    """
+    A background task that periodically renews the lock.
+    """
+    # Renew at 50% of the TTL duration
+    renew_interval = ttl / 2.0
+
+    while not stop_event.wait(renew_interval):
+        try:
+            if not lock.renew(lock_ttl=ttl):
+                # We lost the lock for some reason
+                rich.print(
+                    f"[bold red]Error:[/] Failed to renew lock '{lock._lock_name}'. Lock lost."
+                )
+                break
+        except Exception as e:
+            rich.print(f"[bold red]Heartbeat Error:[/] {e}")
+            break
+
+
+@app.command(
+    "run", context_settings={"allow_extra_args": True, "ignore_unknown_options": True}
+)
+def run_command(
+    ctx: typer.Context,
+    timeout: Annotated[
+        Optional[float],
+        typer.Option(
+            help="Max seconds to wait for the lock. Waits forever by default."
+        ),
+    ] = None,
+    ttl: Annotated[
+        float, typer.Option(help="Seconds the lock can be held before auto-expiring.")
+    ] = 60.0,
+):
+    """
+    Run a command while holding the lock.
+
+    This command will acquire the lock, run your command as a subprocess,
+    and automatically renew the lock in the background until your command
+    finishes.
+
+    Example:
+
+    beaver lock my-cron-job run bash -c 'run_daily_report.sh'
+    """
+    db: BeaverDB = ctx.obj["db"]
+    name = ctx.obj["name"]
+    command: List[str] = ctx.args
+
+    if not command:
+        rich.print("[bold red]Error:[/] No command provided to 'run'.")
+        raise typer.Exit(code=1)
+
+    lock = db.lock(name, timeout=timeout, ttl=ttl)
+    stop_heartbeat = threading.Event()
+    heartbeat_thread = threading.Thread(
+        target=_heartbeat_task, args=(lock, ttl, stop_heartbeat), daemon=True
+    )
+
+    process = None
+    return_code = 1  # Default to error
+
+    try:
+        rich.print(
+            f"[cyan]Waiting to acquire lock '[bold]{name}[/bold]' (Timeout: {timeout or 'inf'})...[/cyan]"
+        )
+        lock.acquire()
+        rich.print(
+            f"[green]Lock acquired. Running command:[/green] {' '.join(command)}"
+        )
+
+        # Start the heartbeat thread AFTER acquiring the lock
+        heartbeat_thread.start()
+
+        # Run the subprocess
+        process = subprocess.Popen(command, shell=False)
+        process.wait()
+        return_code = process.returncode
+
+        if return_code == 0:
+            rich.print(f"[green]Command finished successfully.[/green]")
+        else:
+            rich.print(f"[bold red]Command failed with exit code {return_code}.[/bold]")
+
+    except TimeoutError:
+        rich.print(f"[bold yellow]Timeout:[/] Failed to acquire lock '{name}'.")
+        raise typer.Exit(code=1)
+    except FileNotFoundError:
+        rich.print(
+            f"[bold red]Error:[/] Command not found: '{command[0]}'. Check your system's PATH."
+        )
+        raise typer.Exit(code=127)  # Standard exit code for "command not found"
+    except KeyboardInterrupt:
+        rich.print(
+            "\n[bold yellow]Interrupted.[/bold] Releasing lock and stopping subprocess..."
+        )
+        if process:
+            process.terminate()
+            process.wait()
+        return_code = 130  # Standard exit code for Ctrl+C
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)
+    finally:
+        # Stop the heartbeat and release the lock
+        stop_heartbeat.set()
+        heartbeat_thread.join(timeout=1.0)  # Wait briefly for thread to stop
+        lock.release()
+        rich.print(f"Lock '[bold]{name}[/bold]' released.")
+
+    if return_code != 0:
+        raise typer.Exit(code=return_code)
+
+
+@app.command("clear")
+def clear(ctx: typer.Context):
+    """
+    Forcibly clear all waiters for the lock.
+
+    This removes ALL entries for the lock, including the
+    current holder and all waiting processes.
+    """
+    db: BeaverDB = ctx.obj["db"]
+    name = ctx.obj["name"]
+
+    try:
+        # Use the static method from the core library
+        if db.lock(name).clear():
+            rich.print(f"[green]Success:[/] Cleared lock '[bold]{name}[/bold]'.")
+        else:
+            rich.print(f"[yellow]No waiter on lock[/] '[bold]{name}[/bold]'.")
+    except Exception as e:
+        rich.print(f"[bold red]Error:[/] {e}")
+        raise typer.Exit(code=1)