clidevkit 0.1.0__py3-none-any.whl

clidev/progress.py

@@ -0,0 +1,42 @@
+"""Progress bar context manager: with app.progress("Installing"): ..."""
+
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TimeElapsedColumn
+
+
+class ProgressContext:
+    """Context manager wrapping a rich Progress bar with one indeterminate task.
+
+    with app.progress("Installing"):
+        app.cmd("pip install numpy")
+        app.cmd("pip install pandas")
+    """
+
+    def __init__(self, label: str = "Working", total: int | None = None):
+        self.label = label
+        self.total = total
+        self._progress = Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TimeElapsedColumn(),
+        )
+        self._task_id = None
+
+    def __enter__(self):
+        self._progress.start()
+        self._task_id = self._progress.add_task(self.label, total=self.total)
+        return self
+
+    def advance(self, amount: float = 1):
+        if self._task_id is not None:
+            self._progress.update(self._task_id, advance=amount)
+
+    def set_description(self, text: str):
+        if self._task_id is not None:
+            self._progress.update(self._task_id, description=text)
+
+    def __exit__(self, exc_type, exc, tb):
+        if self._task_id is not None and self.total:
+            self._progress.update(self._task_id, completed=self.total)
+        self._progress.stop()
+        return False

clidev/router.py

@@ -0,0 +1,37 @@
+"""Navigation: app.goto(name), app.back(), history stack."""
+
+from .exceptions import NavigationError
+from .pages import PageRegistry
+
+
+class Router:
+    def __init__(self, app=None):
+        self.app = app
+        self.pages = PageRegistry()
+        self.history: list[str] = []
+        self.current: str | None = None
+
+    def page(self, name: str, handler=None):
+        return self.pages.register(name, handler)
+
+    def goto(self, name: str, *args, **kwargs):
+        page = self.pages.get(name)
+        if page is None:
+            raise NavigationError(f"No page named '{name}' has been registered.")
+        if self.current is not None:
+            self.history.append(self.current)
+        self.current = name
+        return page.render(*args, **kwargs)
+
+    def back(self):
+        if not self.history:
+            raise NavigationError("No previous page to go back to.")
+        previous = self.history.pop()
+        page = self.pages.get(previous)
+        self.current = previous
+        if page is not None:
+            return page.render()
+
+    def reset(self):
+        self.history.clear()
+        self.current = None

clidev/scheduler.py

@@ -0,0 +1,59 @@
+"""Lightweight in-process scheduler for delayed / repeating callbacks."""
+
+import threading
+import time
+
+
+class ScheduledJob:
+    def __init__(self, interval: float, fn, repeat: bool = False):
+        self.interval = interval
+        self.fn = fn
+        self.repeat = repeat
+        self._timer: threading.Timer | None = None
+        self._cancelled = False
+
+    def _run(self):
+        if self._cancelled:
+            return
+        self.fn()
+        if self.repeat and not self._cancelled:
+            self._schedule()
+
+    def _schedule(self):
+        self._timer = threading.Timer(self.interval, self._run)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def start(self):
+        self._schedule()
+        return self
+
+    def cancel(self):
+        self._cancelled = True
+        if self._timer is not None:
+            self._timer.cancel()
+
+
+class Scheduler:
+    """app.scheduler.after(5, fn) / app.scheduler.every(10, fn)"""
+
+    def __init__(self):
+        self.jobs: list[ScheduledJob] = []
+
+    def after(self, seconds: float, fn) -> ScheduledJob:
+        job = ScheduledJob(seconds, fn, repeat=False).start()
+        self.jobs.append(job)
+        return job
+
+    def every(self, seconds: float, fn) -> ScheduledJob:
+        job = ScheduledJob(seconds, fn, repeat=True).start()
+        self.jobs.append(job)
+        return job
+
+    def cancel_all(self):
+        for job in self.jobs:
+            job.cancel()
+        self.jobs.clear()
+
+    def sleep(self, seconds: float):
+        time.sleep(seconds)

clidev/shell.py

@@ -0,0 +1,84 @@
+"""Cross-platform shell / subprocess execution: app.cmd(...)."""
+
+import subprocess
+import threading
+from dataclasses import dataclass
+
+from .exceptions import CommandError
+
+
+@dataclass
+class CommandResult:
+    command: str
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+class BackgroundHandle:
+    """Handle returned for background=True commands."""
+
+    def __init__(self, thread: threading.Thread, popen: subprocess.Popen):
+        self._thread = thread
+        self.popen = popen
+
+    def is_running(self) -> bool:
+        return self.popen.poll() is None
+
+    def wait(self) -> CommandResult:
+        stdout, stderr = self.popen.communicate()
+        self._thread.join()
+        return CommandResult(
+            command=" ".join(self.popen.args) if isinstance(self.popen.args, list) else str(self.popen.args),
+            returncode=self.popen.returncode,
+            stdout=stdout or "",
+            stderr=stderr or "",
+        )
+
+    def terminate(self):
+        self.popen.terminate()
+
+
+class Shell:
+    """Facade exposed as app.cmd via a thin wrapper in App, or used directly."""
+
+    def run(self, command: str, capture: bool = False, background: bool = False,
+             check: bool = False, shell: bool = True, cwd: str | None = None):
+        if background:
+            popen = subprocess.Popen(
+                command,
+                shell=shell,
+                cwd=cwd,
+                stdout=subprocess.PIPE if capture else None,
+                stderr=subprocess.PIPE if capture else None,
+                text=True,
+            )
+            thread = threading.Thread(target=popen.wait, daemon=True)
+            thread.start()
+            return BackgroundHandle(thread, popen)
+
+        result = subprocess.run(
+            command,
+            shell=shell,
+            cwd=cwd,
+            capture_output=capture,
+            text=True,
+        )
+        cmd_result = CommandResult(
+            command=command,
+            returncode=result.returncode,
+            stdout=result.stdout or "" if capture else "",
+            stderr=result.stderr or "" if capture else "",
+        )
+        if check and not cmd_result.ok:
+            raise CommandError(
+                f"Command '{command}' exited with code {cmd_result.returncode}",
+                returncode=cmd_result.returncode,
+                stdout=cmd_result.stdout,
+                stderr=cmd_result.stderr,
+            )
+        return cmd_result

clidev/spinner.py

@@ -0,0 +1,25 @@
+"""Simple indeterminate spinner context manager: with app.spinner("Loading"): ..."""
+
+from rich.console import Console
+from rich.status import Status
+
+
+class Spinner:
+    def __init__(self, label: str = "Loading...", console: Console | None = None):
+        self.label = label
+        self.console = console or Console()
+        self._status: Status | None = None
+
+    def __enter__(self):
+        self._status = self.console.status(self.label)
+        self._status.start()
+        return self
+
+    def update(self, text: str):
+        if self._status is not None:
+            self._status.update(text)
+
+    def __exit__(self, exc_type, exc, tb):
+        if self._status is not None:
+            self._status.stop()
+        return False

clidev/state.py

@@ -0,0 +1,47 @@
+"""Global, dict-like application state: app.state["key"] = value"""
+
+from typing import Any, Callable
+
+
+class State:
+    """A dict-like global state container with optional change listeners."""
+
+    def __init__(self, initial: dict | None = None):
+        self._data: dict[str, Any] = dict(initial or {})
+        self._listeners: list[Callable[[str, Any, Any], None]] = []
+
+    def on_change(self, callback: Callable[[str, Any, Any], None]):
+        """Register a callback(key, old_value, new_value) fired on every set."""
+        self._listeners.append(callback)
+        return callback
+
+    def __getitem__(self, key):
+        return self._data[key]
+
+    def __setitem__(self, key, value):
+        old = self._data.get(key)
+        self._data[key] = value
+        for cb in self._listeners:
+            cb(key, old, value)
+
+    def __delitem__(self, key):
+        del self._data[key]
+
+    def __contains__(self, key):
+        return key in self._data
+
+    def get(self, key, default=None):
+        return self._data.get(key, default)
+
+    def update(self, other: dict):
+        for k, v in other.items():
+            self[k] = v
+
+    def as_dict(self):
+        return dict(self._data)
+
+    def clear(self):
+        self._data.clear()
+
+    def __repr__(self):
+        return f"State({self._data})"

clidev/statusbar.py

@@ -0,0 +1,20 @@
+"""A simple single-line status bar rendered at the bottom of output."""
+
+from rich.console import Console
+
+
+class StatusBar:
+    def __init__(self, theme=None, console: Console | None = None):
+        self.theme = theme
+        self.console = console or Console()
+        self._segments: list[str] = []
+
+    def set(self, *segments: str) -> "StatusBar":
+        self._segments = list(segments)
+        return self
+
+    def render(self):
+        color = self.theme.get("muted") if self.theme else None
+        style = color or "dim"
+        line = "  |  ".join(self._segments)
+        self.console.print(f"[{style}]{line}[/{style}]")

clidev/storage.py

@@ -0,0 +1,221 @@
+"""Pluggable data storage backends: memory, JSON, SQLite, YAML, TOML."""
+
+import json
+import sqlite3
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from .exceptions import StorageError
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    yaml = None
+
+try:
+    import toml
+except ImportError:  # pragma: no cover
+    toml = None
+
+
+class StorageBackend(ABC):
+    @abstractmethod
+    def save(self, name: str, data): ...
+
+    @abstractmethod
+    def load(self, name: str): ...
+
+    @abstractmethod
+    def delete(self, name: str): ...
+
+    @abstractmethod
+    def all(self) -> dict: ...
+
+
+class MemoryStorage(StorageBackend):
+    """Volatile, in-process storage. Data is lost when the app exits."""
+
+    def __init__(self):
+        self._data = {}
+
+    def save(self, name, data):
+        self._data[name] = data
+
+    def load(self, name):
+        return self._data.get(name)
+
+    def delete(self, name):
+        self._data.pop(name, None)
+
+    def all(self):
+        return dict(self._data)
+
+
+class JSONStorage(StorageBackend):
+    """Persists all records to a single JSON file."""
+
+    def __init__(self, path: str = ".clidev_storage.json"):
+        self.path = Path(path)
+        if not self.path.exists():
+            self.path.write_text("{}")
+
+    def _read(self):
+        try:
+            return json.loads(self.path.read_text() or "{}")
+        except json.JSONDecodeError as e:
+            raise StorageError(f"Corrupt JSON storage file: {e}") from e
+
+    def _write(self, data):
+        self.path.write_text(json.dumps(data, indent=2, default=str))
+
+    def save(self, name, data):
+        all_data = self._read()
+        all_data[name] = data
+        self._write(all_data)
+
+    def load(self, name):
+        return self._read().get(name)
+
+    def delete(self, name):
+        data = self._read()
+        data.pop(name, None)
+        self._write(data)
+
+    def all(self):
+        return self._read()
+
+
+class YAMLStorage(StorageBackend):
+    def __init__(self, path: str = ".clidev_storage.yaml"):
+        if yaml is None:
+            raise StorageError("PyYAML is required for YAMLStorage. pip install pyyaml")
+        self.path = Path(path)
+        if not self.path.exists():
+            self.path.write_text("{}")
+
+    def _read(self):
+        return yaml.safe_load(self.path.read_text()) or {}
+
+    def _write(self, data):
+        self.path.write_text(yaml.safe_dump(data))
+
+    def save(self, name, data):
+        all_data = self._read()
+        all_data[name] = data
+        self._write(all_data)
+
+    def load(self, name):
+        return self._read().get(name)
+
+    def delete(self, name):
+        data = self._read()
+        data.pop(name, None)
+        self._write(data)
+
+    def all(self):
+        return self._read()
+
+
+class TOMLStorage(StorageBackend):
+    def __init__(self, path: str = ".clidev_storage.toml"):
+        if toml is None:
+            raise StorageError("toml is required for TOMLStorage. pip install toml")
+        self.path = Path(path)
+        if not self.path.exists():
+            self.path.write_text("")
+
+    def _read(self):
+        content = self.path.read_text()
+        return toml.loads(content) if content.strip() else {}
+
+    def _write(self, data):
+        self.path.write_text(toml.dumps(data))
+
+    def save(self, name, data):
+        all_data = self._read()
+        all_data[name] = data
+        self._write(all_data)
+
+    def load(self, name):
+        return self._read().get(name)
+
+    def delete(self, name):
+        data = self._read()
+        data.pop(name, None)
+        self._write(data)
+
+    def all(self):
+        return self._read()
+
+
+class SQLiteStorage(StorageBackend):
+    """Key-value storage backed by SQLite (values stored as JSON text)."""
+
+    def __init__(self, path: str = ".clidev_storage.db"):
+        self.path = path
+        self._conn = sqlite3.connect(self.path)
+        self._conn.execute(
+            "CREATE TABLE IF NOT EXISTS clidev_kv (name TEXT PRIMARY KEY, value TEXT)"
+        )
+        self._conn.commit()
+
+    def save(self, name, data):
+        self._conn.execute(
+            "INSERT INTO clidev_kv (name, value) VALUES (?, ?) "
+            "ON CONFLICT(name) DO UPDATE SET value=excluded.value",
+            (name, json.dumps(data, default=str)),
+        )
+        self._conn.commit()
+
+    def load(self, name):
+        row = self._conn.execute(
+            "SELECT value FROM clidev_kv WHERE name = ?", (name,)
+        ).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def delete(self, name):
+        self._conn.execute("DELETE FROM clidev_kv WHERE name = ?", (name,))
+        self._conn.commit()
+
+    def all(self):
+        rows = self._conn.execute("SELECT name, value FROM clidev_kv").fetchall()
+        return {name: json.loads(value) for name, value in rows}
+
+    def close(self):
+        self._conn.close()
+
+
+BACKENDS = {
+    "memory": MemoryStorage,
+    "json": JSONStorage,
+    "sqlite": SQLiteStorage,
+    "yaml": YAMLStorage,
+    "toml": TOMLStorage,
+}
+
+
+class Storage:
+    """Facade exposed as app.storage, e.g. app.storage.save("user", data)."""
+
+    def __init__(self, backend: str | StorageBackend = "memory", **kwargs):
+        if isinstance(backend, StorageBackend):
+            self._backend = backend
+        else:
+            if backend not in BACKENDS:
+                raise StorageError(
+                    f"Unknown storage backend '{backend}'. Options: {list(BACKENDS)}"
+                )
+            self._backend = BACKENDS[backend](**kwargs)
+
+    def save(self, name: str, data):
+        self._backend.save(name, data)
+
+    def load(self, name: str, default=None):
+        value = self._backend.load(name)
+        return value if value is not None else default
+
+    def delete(self, name: str):
+        self._backend.delete(name)
+
+    def all(self) -> dict:
+        return self._backend.all()

clidev/table.py

@@ -0,0 +1,39 @@
+"""Table rendering widget, wraps rich.table.Table."""
+
+from rich.console import Console
+from rich.table import Table as RichTable
+
+
+class Table:
+    """app.table("Users", columns=["Name", "Age"]).add_row("Bob", "30").show()"""
+
+    def __init__(self, title: str = "", columns: list[str] | None = None, theme=None):
+        self.title = title
+        self.columns = columns or []
+        self.rows: list[list] = []
+        self.theme = theme
+        self._console = Console()
+
+    def add_column(self, name: str) -> "Table":
+        self.columns.append(name)
+        return self
+
+    def add_row(self, *values) -> "Table":
+        self.rows.append(list(values))
+        return self
+
+    def add_rows(self, rows: list[list]) -> "Table":
+        self.rows.extend(rows)
+        return self
+
+    def build(self) -> RichTable:
+        color = self.theme.get("primary") if self.theme else None
+        rich_table = RichTable(title=self.title or None, header_style=f"bold {color}" if color else "bold")
+        for col in self.columns:
+            rich_table.add_column(col)
+        for row in self.rows:
+            rich_table.add_row(*[str(v) for v in row])
+        return rich_table
+
+    def show(self):
+        self._console.print(self.build())

clidev/tasks.py

@@ -0,0 +1,28 @@
+"""Task registry: @app.task decorator + app.run_task(name)."""
+
+from .exceptions import ClidevError
+
+
+class TaskRegistry:
+    def __init__(self):
+        self._tasks: dict[str, callable] = {}
+
+    def register(self, fn=None, *, name: str | None = None):
+        """Use as @app.task or @app.task(name="custom_name")."""
+        if fn is not None and callable(fn):
+            self._tasks[name or fn.__name__] = fn
+            return fn
+
+        def decorator(f):
+            self._tasks[name or f.__name__] = f
+            return f
+
+        return decorator
+
+    def run(self, name: str, *args, **kwargs):
+        if name not in self._tasks:
+            raise ClidevError(f"No task named '{name}' has been registered.")
+        return self._tasks[name](*args, **kwargs)
+
+    def names(self):
+        return list(self._tasks.keys())