luvz 0.0.1.dev0__tar.gz

luvz-0.0.1.dev0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 luvbyte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

luvz-0.0.1.dev0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: luvz
+Version: 0.0.1.dev0
+Summary: Lazy script builder
+Author-email: luvbyte <lovemelong@protonmail.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: cmd2
+Requires-Dist: rich
+Requires-Dist: pydantic
+Dynamic: license-file
+
+# luvz 💤  
+A lightweight framework for building interactive Python scripts
+
+`luvz` is a Python package built on top of [`cmd2`](https://cmd2.readthedocs.io) that makes it easy to build interactive, command-driven Python programs.  
+It gives you a simple API for defining commands, handling user input, and extending functionality — perfect for creating REPL-like tools, admin shells, or prototypes.
+
+---
+
+## ✨ Features
+
+- Simple API to create interactive command-line applications  
+- Built on `cmd2` for history, tab completion, transcripts, and more  
+- Minimal setup — just subclass and add commands  
+- Great for prototypes, admin utilities, or sharing interactive tools  
+
+---
+
+## 📦 Installation
+
+```bash
+pip install luvz
+```
+
+(or clone and install locally:)
+```bash
+git clone https://github.com/luvbyte/luvz.git
+cd luvz
+pip install .
+```
+---
+## ⚡ Why luvz?
+
+Save time — skip boilerplate when building interactive shells
+
+Enjoy rich features from cmd2 without the setup
+
+Create professional-feeling CLI tools quickly
+

luvz-0.0.1.dev0/README.md

@@ -0,0 +1,38 @@
+# luvz 💤  
+A lightweight framework for building interactive Python scripts
+
+`luvz` is a Python package built on top of [`cmd2`](https://cmd2.readthedocs.io) that makes it easy to build interactive, command-driven Python programs.  
+It gives you a simple API for defining commands, handling user input, and extending functionality — perfect for creating REPL-like tools, admin shells, or prototypes.
+
+---
+
+## ✨ Features
+
+- Simple API to create interactive command-line applications  
+- Built on `cmd2` for history, tab completion, transcripts, and more  
+- Minimal setup — just subclass and add commands  
+- Great for prototypes, admin utilities, or sharing interactive tools  
+
+---
+
+## 📦 Installation
+
+```bash
+pip install luvz
+```
+
+(or clone and install locally:)
+```bash
+git clone https://github.com/luvbyte/luvz.git
+cd luvz
+pip install .
+```
+---
+## ⚡ Why luvz?
+
+Save time — skip boilerplate when building interactive shells
+
+Enjoy rich features from cmd2 without the setup
+
+Create professional-feeling CLI tools quickly
+

luvz-0.0.1.dev0/luvz/__init__.py

@@ -0,0 +1,10 @@
+from .core.context import ZScript, Arg
+from .core.runner import run_script, run_script_cli, run_script_it
+
+__all__ = [
+  "Arg",
+  "ZScript",
+  "run_script",
+  "run_script_it",
+  "run_script_cli"
+]

luvz-0.0.1.dev0/luvz/core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

luvz-0.0.1.dev0/luvz/core/context/__init__.py

@@ -0,0 +1,2 @@
+from .script import ZScript
+from .command import Arg, ScriptCommand

luvz-0.0.1.dev0/luvz/core/context/command.py

@@ -0,0 +1,133 @@
+import cmd2
+import inspect
+
+class Arg:
+  def __init__(self, *args, **kwargs):
+    self.args = args
+    self.kwargs = kwargs
+  
+  @staticmethod
+  def Path(*args, **kwargs):
+    return Arg(completer=cmd2.Cmd.path_complete, *args, **kwargs)
+
+  @staticmethod
+  def Choice(*args, **kwargs):
+    return Arg(choices=[str(name) for name in args], **kwargs)
+
+class ScriptCommand:
+  def __init__(self, name, func, short=None, desc=None):
+    self.name = name
+    self.func = func # callable
+    # Short description
+    self.short = short
+    
+    self.desc = desc or (self.func.__doc__ or "").strip()
+
+    # if desc or get from func desc
+    self.argparser = cmd2.Cmd2ArgumentParser(
+      prog=self.name,
+      description=self.desc
+    )
+    # parse args from function
+    self._parse_func_args()
+
+  def has(self, name):
+    return name in self._registers
+  
+  def get(self, name, default=None):
+    return self._registers.get(name, default)
+
+  def help_text(self, line):
+    return self.argparser.format_help()
+  
+  # Building argparse
+  def _parse_func_args(self):
+    sig = inspect.signature(self.func)
+    for param_name, param in sig.parameters.items():
+      if param.kind == inspect.Parameter.VAR_POSITIONAL:
+        self._add_argument(param_name, nargs='*', help=f"Extra positional args for {param_name}")
+        continue
+      elif param.kind == inspect.Parameter.VAR_KEYWORD:
+        continue
+  
+      if isinstance(param.annotation, Arg):
+        arg = param.annotation
+        # if no default / required positional argument
+        if param.default == inspect._empty:
+          self._add_argument(param_name, *arg.args, **arg.kwargs)
+        else:
+          self._add_argument(f"--{param_name}", *arg.args, default=param.default, **arg.kwargs)
+        continue
+
+      arg_type = param.annotation if param.annotation != inspect._empty else str
+  
+      if param.default == inspect._empty:
+        self._add_argument(param_name, type=arg_type)
+      else:
+        if arg_type is bool:
+          if param.default is False:
+            self._add_argument(f"--{param_name}", action="store_true", default=False)
+          else:
+            self._add_argument(f"--no-{param_name}", action="store_false", dest=param_name, default=True)
+        else:
+          self._add_argument(f"--{param_name}", type=arg_type, default=param.default)
+
+  def _add_argument(self, *args, **kwargs):
+    self.argparser.add_argument(*args, **kwargs)
+
+  def emit_func(self, *args, **kwargs):
+    return self.func(*args, **kwargs) if callable(self.func) else self.func
+  
+  # args will be cmd2 Namespace()
+  def run(self, args):
+    import inspect
+
+    # Convert argparse Namespace to dict
+    if not isinstance(args, dict):
+      arg_dict = vars(args)
+    else:
+      arg_dict = args
+
+    sig = inspect.signature(self.func)
+    positional = []
+    keywords = {}
+    varargs = []
+    extra_kwargs = {}
+
+    for name, param in sig.parameters.items():
+      if param.kind == inspect.Parameter.VAR_POSITIONAL:
+        # collect *args
+        varargs = arg_dict.get(name, [])
+      elif param.kind == inspect.Parameter.VAR_KEYWORD:
+        # collect remaining kwargs not already matched
+        for k, v in arg_dict.items():
+          if k not in sig.parameters:
+            extra_kwargs[k] = v
+      else:
+        # normal positional or keyword parameters
+        if name in arg_dict:
+          if param.default is inspect._empty:
+            # no default → positional
+            positional.append(arg_dict[name])
+          else:
+            # has default → keyword
+            keywords[name] = arg_dict[name]
+
+    # Call the function
+    return self.func(*positional, *varargs, **keywords, **extra_kwargs)
+
+  def run_cli(self, args):
+    return self.run(self.argparser.parse_args(args))
+
+class ScriptCommands:
+  def __init__(self):
+    self._registers = {}
+  
+  def items(self):
+    return self._registers.items()
+  
+  def get(self, name, default=None):
+    return self._registers.get(name, default)
+
+  def add(self, name, func, *args, **kwargs):
+    self._registers[name] = ScriptCommand(name, func, *args, **kwargs)

luvz-0.0.1.dev0/luvz/core/context/script.py

@@ -0,0 +1,199 @@
+import os
+import sys
+import cmd2
+import inspect
+
+from uuid import uuid4
+from pathlib import Path
+
+from luvz.modules.process import sh
+from luvz.utils.path import ensure_dir
+from luvz.modules.console import AdvConsole
+from luvz.core.models.script import ScriptConfigModel
+
+from .task import ScriptTasks
+from .command import ScriptCommands, Arg
+
+
+# ---- script events 
+
+class ScriptEvent:
+  def __init__(self, name, func, *args, **kwargs):
+    self.name = name
+    self.func = func
+  
+  def emit(self, *args, **kwargs):
+    return self.func(*args, **kwargs)
+
+class ScriptEvents:
+  def __init__(self):
+    self._registers = {}
+
+  def add(self, name: str, func, *args, **kwargs) -> ScriptEvent:
+    event = ScriptEvent(name, func, *args, **kwargs)
+    self._registers.setdefault(name, []).append(event)
+    
+    return event
+
+  def has(self, name: str):
+    return name in self._registers
+  
+  def get(self, name, default=None):
+    return self._registers.get(name, default)
+
+  def emit(self, name, *args, **kwargs):
+    for ev in self._registers.get(name, []):
+      ev.emit(*args, **kwargs)
+
+# ---- Config and ZOptions
+
+class ScriptConfig:
+  def __init__(self, config: ScriptConfigModel):
+    self._config = config
+    self.luvz_path = ensure_dir(Path.home() / ".luvz")
+
+class ScriptOption:
+  def __init__(self, name, value=None, require=False, type=str, choices=(), help=None):
+    self.name = name
+    self._value = value          # store actual value internally
+    self._type = type
+    self.choices = choices
+    self.require = require
+    
+    self.help = help
+
+  @property
+  def value(self):
+    """Return the value, enforcing 'require' rule."""
+    if self.require and self._value is None:
+      raise ValueError(f"Required option '{self.name}' is missing a value")
+    return self._value
+
+  @value.setter
+  def value(self, new_value):
+    # 1. cast the input
+    try:
+      casted = self._type(new_value)
+    except (ValueError, TypeError):
+      raise TypeError(
+        f"Option '{self.name}' expects type {self._type.__name__}, "
+        f"but got {new_value!r} of type {type(new_value).__name__}"
+      )
+
+    # 2. cast the choices to _type too, once, to be safe
+    if self.choices:
+      try:
+        normalized_choices = tuple(self._type(c) for c in self.choices)
+      except (ValueError, TypeError):
+        raise ValueError(f"Choices for option '{self.name}' cannot be cast to {self._type.__name__}")
+      if casted not in normalized_choices:
+        raise ValueError(
+          f"Invalid value for option '{self.name}': {casted!r}. "
+          f"Allowed choices: {normalized_choices}"
+        )
+
+    # 3. enforce require
+    if self.require and casted is None:
+      raise ValueError(f"Cannot set None for required option '{self.name}'")
+
+    self._value = casted
+  
+  def __str__(self):
+    return self.value or ""
+
+class ScriptOptions:
+  def __init__(self):
+    self._options = {}
+  
+  def add(self, name, *args, **kwargs):
+    option = ScriptOption(name, *args, **kwargs)
+    self._options[name] = option
+    return option
+  
+  # sets option else raises error
+  def set(self, name, value):
+    if name not in self._options:
+      raise KeyError(f"Option '{name}' does not exist")
+    self._options[name].value = value
+
+  # returns direct value
+  def get(self, name):
+    if name not in self._options:
+      raise KeyError(f"Option '{name}' does not exist")
+    return self._options[name].value
+  
+  def __call__(self, name):
+    return self.get(name)
+
+# ---- Script Args (argv)
+
+class ScriptArgs:
+  def __init__(self):
+    self._raw_args = sys.argv[1:]
+
+  def get(self, index, default=None):
+    try:
+      return self._raw_args[index]
+    except ValueError:
+      return default
+  
+  def __str__(self):
+    return " ".join(self._raw_args)
+
+# ---- ZScript
+
+class ZScript:
+  prompt = "| "
+  banner = None
+  def __init__(self, name=None, version=None, author=None, desc=None, config={}):
+    # script paths
+    self.script_full_path = Path(sys.argv[0])
+    self.script_path = self.script_full_path.parent
+    
+    # with ext
+    self.script_name = os.path.basename(sys.argv[0])
+    # script meta
+    self.name = (name or Path(sys.argv[0]).with_suffix("").name).capitalize()
+    self.desc = desc
+    self.author = author
+    self.version = version
+
+    self.scr = AdvConsole()
+    self.options = ScriptOptions()
+    self.config = ScriptConfig(ScriptConfigModel(**config))
+
+    self.events = ScriptEvents()
+    self.commands = ScriptCommands()
+    self.tasks = ScriptTasks()
+
+    self.sh = sh
+    # finally parsing args
+    self.args = ScriptArgs()
+
+  @property
+  def cwd(self):
+    return os.getcwd()
+
+  def arg(self, *args, **kwargs):
+    return Arg(*args, **kwargs)
+
+  def add_option(self, *args, **kwargs):
+    return self.options.add(*args, **kwargs)
+
+  def on(self, name, *args, **kwargs):
+    def wrapper(func):
+      if name.startswith("luvz:"):
+        self.events.add(name[4:], func, *args, **kwargs)
+      else:
+        self.commands.add(name, func, *args, **kwargs)
+    return wrapper
+
+  def on_event(self, name, *args, **kwargs):
+    def wrapper(func):
+      self.events.add(name, func, *args, **kwargs)
+    return wrapper
+
+  def __call__(self, cmd):
+    if cmd.startswith("$"):
+      return self.sh(cmd[1:])
+

luvz-0.0.1.dev0/luvz/core/context/task.py

@@ -0,0 +1,13 @@
+from uuid import uuid4
+
+
+class ScriptTask:
+  def __init__(self, name):
+    self.uid = uuid4().hex
+    self.name = name
+
+class ScriptTasks:
+  def __init__(self):
+    # taskID - Task
+    self._active = {}
+

luvz-0.0.1.dev0/luvz/core/models/script.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel
+
+class ScriptConfigModel(BaseModel):
+  pass
+

luvz-0.0.1.dev0/luvz/core/runner/__init__.py

@@ -0,0 +1,13 @@
+import sys
+
+# ------ Run types
+def run_script_it(script, intro: bool = True):
+  from .interactive import ZScriptRunner
+  return ZScriptRunner(script).run(intro=intro)
+
+def run_script_cli(script, intro: bool = False):
+  from .cli import ZScriptRunnerCli
+  return ZScriptRunnerCli(script).run(intro=intro)
+
+def run_script(script, *args, **kwargs):
+  return run_script_cli(script, *args, **kwargs) if len(sys.argv) > 1 else run_script_it(script, *args, **kwargs)

luvz-0.0.1.dev0/luvz/core/runner/base.py

@@ -0,0 +1,167 @@
+from rich.table import Table
+from luvz.core import __version__
+
+import atexit
+
+BANNER = r"""
+[blue]███████╗███████╗███████╗[/]
+╚══███╔╝╚══███╔╝╚══███╔╝
+[red]  ███╔╝   ███╔╝   ███╔╝ [/]
+ ███╔╝   ███╔╝   ███╔╝  
+[yellow]███████╗███████╗███████╗[/]
+╚══════╝╚══════╝╚══════╝
+"""
+BANNER = r"""
+|   _    _   ___     _______
+|  | |  | | | \ \   / /__  /
+|  | |  | | | |\ \ / /  / / 
+|  | |__| |_| | \ V /  / /_ 
+|  |_____\___/   \_/  /____|
+                          
+"""
+BANNER = r"""
+[blue]██╗      ██╗   ██╗ ██╗   ██╗ ███████╗[/]
+██║      ██║   ██║ ██║   ██║ ╚══███╔╝
+[red]██║      ██║   ██║ ██║   ██║   ███╔╝ [/]
+██║      ██║   ██║ ╚██╗ ██╔╝  ███╔╝  
+[yellow]███████╗ ╚██████╔╝  ╚████╔╝  ███████╗[/]
+╚══════╝  ╚═════╝    ╚═══╝   ╚══════╝
+"""
+
+class RunnerUtils:
+  def __init__(self, script):
+    self.script = script
+    atexit.register(self.__on_exit)
+    # emiting init
+    self.script.events.emit("init")
+
+  @property
+  def scr(self): # global scr for runners
+    return self.script.scr
+  
+  def print_header(self):
+    self.scr.print_center(self.script.banner or BANNER)
+    self.scr.print_center(f"luvz: [blue]luvbyte[/blue] | version: [red]{__version__}[/red]")
+
+  def print_script_header(self):
+    # Script header
+    version = f" [red]v{self.script.version}[/red]" if self.script.version else ""
+    author = self.script.author if self.script.author else "Someone [red]ᥫ᭡[/red]"
+    self.scr.print_panel(f"✨ [blue]{self.script.name}[/blue]{version} by [green]{author}[/green]", padding=False)
+  
+  def print_intro(self):
+    # if banner found print it
+    if self.script.banner:
+      self.scr.print_center(self.script.banner)
+    # if its False then dont print any banner
+    elif self.script.banner is not False:
+      self.print_header()
+
+    # script details
+    self.print_script_header()
+
+  def _print_commands(self, cmd2_commands: bool):
+    commands = list(self.script.commands.items())
+
+    self.scr.print_center(f"[italic magenta]{'No' if not cmd2_commands and len(commands) <= 0 else ''} Available Commands[/italic magenta]")
+
+    # Split based on with and without short descriptions
+    no_short, with_short = [], []
+    for name, cmd in commands:
+      (with_short if cmd.short else no_short).append((name, getattr(cmd, 'short', None)))
+
+    if with_short or cmd2_commands:
+      table = Table(header_style="bold cyan", border_style="blue", expand=True)
+      table.add_column("Command", style="green")
+      table.add_column("Description", style="yellow")
+
+      # Predefined cmd2_commands rows
+      if cmd2_commands:
+        builtin_commands = {
+          "alias": "Create command shortcuts",
+          "edit": "Edit a script or configuration",
+          "help": "Show help (use 'help -v' for verbose)",
+          "history": "Show command history",
+          "macro": "Record or play macros",
+          "quit": "Exit the program",
+          "run_pyscript": "Run a Python script",
+          "run_script": "Run a script",
+          "set": "Set configuration options",
+          "shell": "Run shell commands",
+          "shortcuts": "List available keyboard shortcuts",
+          "options": "Script options",
+          "commands": "Script commands",
+          "zset": "Set ZOption",
+          "---": "---"
+        }
+        for name, desc in builtin_commands.items():
+          table.add_row(name, desc)
+
+      # Add user commands with short descriptions
+      for name, desc in with_short:
+        table.add_row(name, desc)
+
+      self.scr.print(table)
+
+    if no_short:
+      names = " ".join(name for name, _ in no_short)
+      self.scr.print_panel(f"[blue]{names}[/blue]", padding=False)
+
+  def print_commands_cmd2(self):
+    return self._print_commands(True)
+
+  def print_commands_cli(self):
+    return self._print_commands(False)
+
+  def print_options(self, required_only: bool = False):
+    options = self.script.options._options
+
+    # Filter only required options if present
+    if required_only:
+      options = {name: opt for name, opt in options.items() if opt.require}
+
+    if not options:
+      return self.scr.print_center(
+        f"[italic red]Script has no{' required' if required_only else ''} options[/italic red]"
+      )
+
+    table = Table(
+      title=f"[blue]Script{' Required' if required_only else ''} Options[/blue]",
+      expand=True
+    )
+
+    for col, style in [
+      ("Name", "cyan"),
+      ("Value", "green"),
+      ("Required", "magenta"),
+      ("Type", "yellow"),
+      ("Choices", "blue")
+    ]:
+      table.add_column(col, style=style, no_wrap=(col == "Name"))
+
+    for name, opt in options.items():
+      # Safely retrieve value
+      try:
+        val = opt.value
+      except Exception:
+        val = "[red]-[/red]"
+
+      # Choices fallback to "-"
+      choices = ", ".join(map(str, getattr(opt, "choices", []))) or "-"
+
+      table.add_row(
+        name,
+        str(val),
+        "Yes" if getattr(opt, "require", False) else "No",
+        getattr(opt._type, "__name__", str(opt._type)),
+        choices
+      )
+
+    self.scr.print(table)
+  
+  def __on_exit(self):
+    self.script.events.emit("exit")
+
+  def exception(self, text):
+    self.scr.print(f"[red]Error:[/red] luvz: [blue]{text}[/blue]")
+

luvz-0.0.1.dev0/luvz/core/runner/cli.py

@@ -0,0 +1,50 @@
+from .base import RunnerUtils
+
+from luvz.core.context import ZScript
+
+
+# cli
+class ZScriptRunnerCli:
+  def __init__(self, script: ZScript):
+    self.script = script
+    self.utils = RunnerUtils(self.script)
+
+    self.script.events.emit("cli:init")
+
+  @property
+  def scr(self):
+    return self.utils.scr
+
+  def _display_cli_help(self):
+    self.utils.print_script_header()
+    self.scr.print(f"[red]Usage[/red]: {self.script.script_name} command [ARGS] [-h]")
+    self.scr.br()
+
+    self.utils.print_commands_cli()
+    
+  def run(self, intro: bool = False):
+    self.script.events.emit("run")
+    args = self.script.args._raw_args
+
+    if len(args) <= 0:
+      args = ["-h"]
+
+    command = args[0]
+    command_args = args[1:]
+
+    # Show help
+    if command in ("-h", "--help"):
+      return self._display_cli_help()
+  
+    if intro:
+      self.utils.print_intro()
+    
+    func = self.script.commands.get(command)
+    if func is None:
+      self.exception(f"command '{command}' not found")
+      return self.scr.br()
+
+    func.run_cli(command_args)
+  
+  def exception(self, text):
+    self.utils.exception(text)

luvz-0.0.1.dev0/luvz/core/runner/interactive.py

@@ -0,0 +1,217 @@
+import os
+import sys
+import types
+import argparse
+
+from pathlib import Path
+from datetime import datetime
+from cmd2 import Cmd, Cmd2ArgumentParser, with_argparser
+
+from rich.text import Text
+from rich.table import Table
+
+from luvz.modules.process import sh
+from .base import BANNER, RunnerUtils
+from luvz.core.context import ZScript, ScriptCommand
+
+
+def make_options_parser():
+  # script argparser
+  script_argparse = Cmd2ArgumentParser()
+  script_argparse.add_argument(
+    'subcommand',
+    nargs="?",
+    choices=['required'],
+    help='Display only required options'
+  )
+  return script_argparse
+
+def make_commands_parser():
+  # script argparser
+  script_argparse = Cmd2ArgumentParser()
+  script_argparse.add_argument(
+    'subcommand',
+    nargs="?",
+    choices=['all'],
+    help='Display all commands list'
+  )
+  return script_argparse
+
+def make_cd_parser():
+  # script argparser
+  cd_argparse = Cmd2ArgumentParser()
+  cd_argparse.add_argument('path', nargs="?", default=Path.home(), help='Change current directory')
+  return cd_argparse
+
+
+# cmd2 - interactive
+class ZScriptRunner(Cmd):
+  def __init__(self, script: ZScript):
+    # bypassing cmd2 default argparse :)
+    original_argv = sys.argv.copy()
+    sys.argv = [sys.argv[0]]
+    # init of Cmd
+    super().__init__()
+    # restoring argv
+    self.script = script
+    sys.argv = original_argv
+
+    self._register_commands()
+
+    self.utils = RunnerUtils(self.script)
+    self.script.events.emit("it:init")
+
+  # arg parser
+  def _register_commands(self):
+    for name, command in self.script.commands.items():
+      desired_prog = command.argparser.prog or name
+
+      @with_argparser(command.argparser)
+      def do_func(inner_self, args, cmd=command):
+        try:
+          cmd.run(args)
+        except Exception as e:
+          inner_self.exception(e)
+
+      # cmd2's decorator changes both the argparser.prog and the function name
+      # Fix them back:
+      do_func.argparser.prog = desired_prog    # fixes Usage: text
+      do_func.__name__ = f"do_{name}"  # fixes command name in help
+      do_func.__qualname__ = f"do_{name}"  # also for introspection
+
+      # finally bind the method to your instance
+      setattr(self, f"do_{name}", types.MethodType(do_func, self))
+
+  @property
+  def scr(self):
+    return self.utils.scr
+
+  @property
+  def prompt(self):
+    prompt = self.script.events.emit("prompt") or self.script.prompt
+    return prompt() if callable(prompt) else prompt
+
+  # --- commands
+  def do_clear(self, _):
+    self.scr.clear()
+
+  def do_ls(self, line):
+    sh(f"ls --color {line}").run()
+
+  def do_pwd(self, _):
+    self.scr.print(f"You are in: {os.getcwd()}")
+
+  def do_exit(self, _):
+    return True
+
+  def complete_cd(self, text, line, begidx, endidx):
+    return [
+      str(path) for path in self.path_complete(text, line, begidx, endidx)
+      if os.path.isdir(path)
+    ]
+
+  # Change Directory
+  @with_argparser(make_cd_parser())
+  def do_cd(self, args):
+    try:
+      os.chdir(args.path)
+    except FileNotFoundError:
+      self.exception(f"No such directory: '[green]{args.path}[/green]'")
+    except Exception as e:
+      self.exception(e)
+
+  # ---- script
+  @with_argparser(make_options_parser())
+  def do_options(self, args):
+    if args.subcommand == "required":
+      self.utils.print_options(True)
+    else:
+      self.utils.print_options(False)
+
+  @with_argparser(make_commands_parser())
+  def do_commands(self, args):
+    if args.subcommand == "all":
+      self.utils.print_commands_cmd2()
+    else:
+      self.utils._print_commands(False)
+
+  #--- setting option
+  def help_zset(self):
+    self.scr.print("[red]Usage[/red]: zset <name> <value>\n\nSET ZOption\n")
+
+  def complete_zset(self, text, line, begidx, endidx):
+    tokens = line.split()
+
+    # Suggest option names when typing the option name
+    if len(tokens) <= 1 or (begidx <= len(tokens[0]) + 1):
+      return [name for name in self.script.options._options if name.startswith(text)]
+
+    opt_name = tokens[1]
+
+    # If typing the value
+    if opt_name in self.script.options._options:
+      opt = self.script.options._options[opt_name]
+
+      # If the option has choices, show choices matching text
+      if opt.choices:
+        return [str(c) for c in opt.choices if str(c).startswith(text)]
+
+      # Otherwise, use cmd2 built-in path completer
+      return self.path_complete(text, line, begidx, endidx)
+
+    return []
+
+  def do_zset(self, line):
+    if not line:
+      self.scr.print("[red]Usage[/red]: zset <name> <value>\n")
+
+    elif len(line.arg_list) < 2:
+      self.scr.print("[red]Missing[/red]: <value>\n")
+    else:
+      try:
+        # set
+        name = line.arg_list[0]
+        value = " ".join(line.arg_list[1:])
+        
+        self.script.options.set(name, value)
+        self.scr.print(f"[red]Updated[/red]: {name}={value}\n")
+      except Exception as e:
+        self.exception(e.args[0])
+  # ---
+
+  def complete_help(self, text, line, begidx, endidx):
+    commands = [name[3:] for name in dir(self) if name.startswith('do_') and not name.startswith("do__")]
+    if not text:
+      return commands
+    return [cmd for cmd in commands if cmd.startswith(text)]
+
+  def do_help(self, line):
+    if line:
+      return super().do_help(line)
+    
+    self.scr.print_panel("[red]Usage[/red]: command [ARGS] [-h]", padding=False)
+    self.utils.print_commands_cmd2()
+    self.utils.print_options()
+
+  # ---- default
+  def default(self, line):
+    event = self.script.events.get("it:default")
+    if event:
+      return event.emit(line)
+    self.scr.print(f"[blue]luvz[/blue]: Unknown command: [red]{line.command}[/red]")
+
+  # ---- starts from here
+  def run(self, clear: bool = True, intro: bool = True):
+    self.script.events.emit("run")
+    if clear:
+      self.scr.clear()
+
+    if intro:
+      self.utils.print_intro()
+    
+    self.cmdloop()
+    self.script.events.emit("run")
+
+  # Exception handling
+  def exception(self, text):
+    self.utils.exception(text)

luvz-0.0.1.dev0/luvz/modules/console.py

@@ -0,0 +1,188 @@
+import os
+import sys
+import time
+import atexit
+import select
+
+from rich.text import Text
+from rich.panel import Panel
+from rich.align import Align
+from rich.table import Table
+from rich.console import Console
+from rich.columns import Columns
+
+from typing import Literal
+
+
+class AdvConsole(Console):
+  def __init__(self) -> None:
+    super().__init__()
+
+    atexit.register(self.__on_exit)
+
+  # hide / show cursor
+  def hide_cursor(self, hide: bool = True) -> None:
+    if hide:
+      sys.stdout.write("\033[?25l")  # Hide cursor
+    else:
+      sys.stdout.write("\033[?25h")  # Show cursor when stopping
+
+  # clear screen
+  def clear(self) -> None:
+    os.system("cls" if os.name == "nt" else "clear")  # Windows: cls, Linux/macOS: clear
+
+  # print empty lines
+  def br(self, lines: int = 1) -> None:
+    self.print(end="\n"*lines)
+
+  # print panel
+  def print_panel(
+    self,
+    content,
+    title: str = "",
+    subtitle: str = "",
+    justify: Literal['left', 'right', 'center'] = "left",
+    padding: bool = True,
+    expand: bool = True,
+    markup: bool = True
+  ) -> None:
+    # Add padding if requested
+    if padding:
+      content = f"\n{content}\n"
+
+    # Create Text safely depending on markup flag
+    if markup:
+      text_obj = Text.from_markup(content, justify=justify)
+    else:
+      text_obj = Text(content, justify=justify)
+
+    # Print Panel with text object
+    self.print(
+      Panel(
+        text_obj,
+        title=title,
+        subtitle=subtitle,
+        expand=expand
+      )
+    )
+
+  # print text with align
+  def print_text(self, text, markup: bool = True, align: Literal['left', 'right', 'center'] = "left"):
+    text = Text.from_markup(text) if markup else Text(text)
+    self.print(Align(text, align = align))
+
+  def print_center(self, text: str, markup: bool = True):
+    self.print_text(text, markup, "center")
+
+  # equal=True, expand=True
+  def columns(self, *args, **kwargs):
+    return Columns(*args, **kwargs)
+
+  def panel(self, *args, **kwargs):
+    return Panel(*args, **kwargs)
+
+  def print_list(
+    self,
+    items,
+    border: bool = True,
+    multi: bool = False,
+    title: str | None = None,
+    expand: bool = True,
+    equal: bool = True,
+    style: str = "white",
+    index_color: str = "cyan"
+  ) -> None:
+    if not items:
+      raise Exception("Items list cannot be empty")
+
+    # Numbered items with style
+    numbered_items = [
+      f"[bold {index_color}]{i}.[/bold {index_color}] [bold {style}]{item}[/bold {style}]"
+      for i, item in enumerate(items, start=1)
+    ]
+
+    # Build layout
+    if multi:
+      cpanel = Columns(numbered_items, expand=expand, equal=equal)
+    else:
+      cpanel = "\n".join(numbered_items)
+
+    # Render with or without panel
+    if border:
+      self.print(Panel(cpanel, title=title, expand=expand))
+    else:
+      self.print(cpanel)
+  
+  def print_table(
+    self, 
+    columns, 
+    rows, 
+    title=None, 
+    header_style="bold cyan",
+    border_style="blue",
+    col_style="green"
+  ):
+    table = Table(
+      title=f"[bold magenta]{title}[/bold magenta]" if title else None,
+      header_style=header_style,
+      border_style=border_style
+    )
+
+    # Add columns
+    for col in columns:
+      table.add_column(col, style=col_style)
+
+    # Add rows
+    for row in rows:
+      table.add_row(*[str(item) for item in row])
+  
+    self.print(table)
+
+  # True - completed, False - canceled
+  def wait_basic(self, seconds: float = 5, message="(Ctrl + C to stop)") -> bool:
+    """Waits with a countdown, allows interruption with Ctrl+C."""
+    try:
+      self.hide_cursor()  # Hide cursor
+      for i in reversed(range(0, seconds)):
+        print(f"{message} : {i} ", end="\r", flush=True)
+        time.sleep(1)
+      return True  # Completed successfully
+    except KeyboardInterrupt:
+      # print("\nInterrupted!")
+      return False  # Interrupted by user
+    finally:
+      self.hide_cursor(False)  # Show cursor
+      sys.stdout.flush()
+
+  def wait(self, timeout: float = 5.0, message: str = "Time remaining") -> bool:
+    try:
+      self.hide_cursor()  # Hide
+      start_time = time.time()
+      while True:
+        elapsed = time.time() - start_time
+        remaining = max(0, int(timeout - elapsed))
+        # print(f"{message} : {remaining}", end="\r", flush=True)
+        sys.stdout.write(f"\r{message} : {remaining}")
+        sys.stdout.flush()
+  
+        # Check for input every 0.1s
+        if sys.stdin in select.select([sys.stdin], [], [], 0.1)[0]:
+          line = sys.stdin.readline()
+          print()  # Move to next line after user input
+          return True if line == '\n' else False
+
+        if elapsed >= timeout:
+          return True
+    except KeyboardInterrupt:
+      return False
+    finally:
+      self.hide_cursor(False)  # Show cursor
+      sys.stdout.write("\r\033[K")
+      sys.stdout.flush()
+
+  # clean up
+  def __on_exit(self) -> None:
+    self.hide_cursor(False)
+
+def convert_markup_to_text(markup_text) -> str:
+  return Text.from_markup(markup_text).plain

luvz-0.0.1.dev0/luvz/modules/process.py

@@ -0,0 +1,56 @@
+import sys
+
+from os import getcwd
+from subprocess import Popen, PIPE
+
+
+class Process:
+  def __init__(self, proc: Popen):
+    self._process = proc
+  
+  def wait(self) -> 'Process':
+    self._process.wait()
+    return self
+
+  def output(self) -> str:
+    if self._process.stdout:
+      output = self._process.stdout.read().decode("utf-8").strip()
+      return output
+    return ""
+
+  @property
+  def returncode(self) -> int:
+    return self._process.returncode
+
+class ProcessBuilder:
+  def __init__(self, cmd: str) -> None:
+    self.cmd: str = cmd
+    self.stdin = PIPE
+    self.stdout = PIPE
+    self.stderr = PIPE
+    self.shell: bool = True
+    self.cwd: str = getcwd()
+
+  def pipe(self) -> Process:
+    return self._run()
+
+  def run(self) -> Process:
+    self.stdin = sys.stdin
+    self.stdout = sys.stdout
+    self.stderr = sys.stderr
+    return self._run()
+
+  def _run(self) -> Process:
+    proc = Popen(
+      self.cmd,
+      cwd=self.cwd,
+      shell=self.shell,
+      stdin=self.stdin,
+      stdout=self.stdout,
+      stderr=self.stderr,
+    )
+    return Process(proc).wait()
+
+
+def sh(cmd: str) -> ProcessBuilder:
+  return ProcessBuilder(cmd)

luvz-0.0.1.dev0/luvz/utils/__init__.py

@@ -0,0 +1 @@
+from .path import ensure_dir

luvz-0.0.1.dev0/luvz/utils/cli.py

@@ -0,0 +1,9 @@
+import sys
+
+from typing import Optional
+
+def read_from_stdin() -> Optional[str]:
+  if sys.stdin.isatty():  # True if running in terminal, no pipe
+      return None
+  return sys.stdin.read()
+

luvz-0.0.1.dev0/luvz/utils/parser.py

@@ -0,0 +1,44 @@
+import json
+from pathlib import Path
+from typing import IO, Any, Optional, Type, Union
+from pydantic import BaseModel, ValidationError
+
+def parse_file(
+  file: IO | dict,
+  model: Optional[Type[BaseModel]] = None,
+  parse_type: str = "json"
+) -> Any:
+  try:
+    if parse_type == "dict":
+      data = file
+    elif parse_type == "json":
+      data = json.load(file)
+    else:
+      raise Exception(f"Unsupported parse type: {parse_type}")
+  except Exception as e:
+    raise Exception(f"Failed to parse file as {parse_type}: {e}")
+
+  if model is None:
+    return data
+
+  try:
+    return model.model_validate(data)
+  except ValidationError:
+    raise Exception(f"Invalid structure for model {model.__name__}")
+
+def parse_config(
+  file_path: Union[str, Path, dict],
+  model: Optional[Type[BaseModel]] = None,
+  parse_type: str = "json"
+) -> Any:
+  try:
+    if isinstance(file_path, dict):
+      return parse_file(file_path, model, "dict")
+    with open(file_path, "r") as file:
+      return parse_file(file, model, parse_type)
+  except FileNotFoundError:
+    raise FileNotFoundError(f"Config file not found: {file_path}")
+  except json.JSONDecodeError:
+    raise json.JSONDecodeError(f"Invalid JSON format: {file_path}")
+  except Exception as e:
+    raise Exception(f"Unexpected error parsing {file_path}: {e}")

luvz-0.0.1.dev0/luvz/utils/path.py

@@ -0,0 +1,7 @@
+from pathlib import Path
+
+from typing import Union
+
+def ensure_dir(path: Union[Path, str]) -> Path:
+  Path(path).mkdir(parents=True, exist_ok=True)
+  return path

luvz-0.0.1.dev0/luvz.egg-info/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: luvz
+Version: 0.0.1.dev0
+Summary: Lazy script builder
+Author-email: luvbyte <lovemelong@protonmail.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: cmd2
+Requires-Dist: rich
+Requires-Dist: pydantic
+Dynamic: license-file
+
+# luvz 💤  
+A lightweight framework for building interactive Python scripts
+
+`luvz` is a Python package built on top of [`cmd2`](https://cmd2.readthedocs.io) that makes it easy to build interactive, command-driven Python programs.  
+It gives you a simple API for defining commands, handling user input, and extending functionality — perfect for creating REPL-like tools, admin shells, or prototypes.
+
+---
+
+## ✨ Features
+
+- Simple API to create interactive command-line applications  
+- Built on `cmd2` for history, tab completion, transcripts, and more  
+- Minimal setup — just subclass and add commands  
+- Great for prototypes, admin utilities, or sharing interactive tools  
+
+---
+
+## 📦 Installation
+
+```bash
+pip install luvz
+```
+
+(or clone and install locally:)
+```bash
+git clone https://github.com/luvbyte/luvz.git
+cd luvz
+pip install .
+```
+---
+## ⚡ Why luvz?
+
+Save time — skip boilerplate when building interactive shells
+
+Enjoy rich features from cmd2 without the setup
+
+Create professional-feeling CLI tools quickly
+

luvz-0.0.1.dev0/luvz.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+LICENCE
+README.md
+pyproject.toml
+luvz/__init__.py
+luvz.egg-info/PKG-INFO
+luvz.egg-info/SOURCES.txt
+luvz.egg-info/dependency_links.txt
+luvz.egg-info/requires.txt
+luvz.egg-info/top_level.txt
+luvz/core/__init__.py
+luvz/core/context/__init__.py
+luvz/core/context/command.py
+luvz/core/context/script.py
+luvz/core/context/task.py
+luvz/core/models/script.py
+luvz/core/runner/__init__.py
+luvz/core/runner/base.py
+luvz/core/runner/cli.py
+luvz/core/runner/interactive.py
+luvz/modules/console.py
+luvz/modules/process.py
+luvz/utils/__init__.py
+luvz/utils/cli.py
+luvz/utils/parser.py
+luvz/utils/path.py

luvz-0.0.1.dev0/luvz.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

luvz-0.0.1.dev0/luvz.egg-info/requires.txt

@@ -0,0 +1,3 @@
+cmd2
+rich
+pydantic

luvz-0.0.1.dev0/luvz.egg-info/top_level.txt

@@ -0,0 +1 @@
+luvz

luvz-0.0.1.dev0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "luvz"
+version = "0.0.1.dev0"
+description = "Lazy script builder"
+authors = [{name="luvbyte", email="lovemelong@protonmail.com"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["cmd2", "rich", "pydantic"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["luvz*"]

luvz-0.0.1.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+