ppui 2026.1.20.2__py3-none-any.whl

ppui/__init__.py

@@ -0,0 +1,27 @@
+from .core import (
+    console,
+    prompt_yes_no,
+    copy_to_clipboard,
+    prompt_toolkit_menu,
+    format_menu_choices,
+    Menu
+)
+from .base import (
+    UIElement,
+    Selection,
+    Option,
+    Presentable
+)
+
+__all__ = [
+    "console",
+    "prompt_yes_no",
+    "copy_to_clipboard",
+    "prompt_toolkit_menu",
+    "format_menu_choices",
+    "Menu",
+    "UIElement",
+    "Selection",
+    "Option",
+    "Presentable"
+]

ppui/base.py

@@ -0,0 +1,47 @@
+"""
+Base abstractions for the PPUI (Python Process User Intent) system.
+"""
+from abc import ABC, abstractmethod
+from typing import Any, List, Optional, Callable, Dict, Union
+
+class Presentable(ABC):
+    """Base class for anything that can be presented to a user (TUI, Web, Voice, etc.)"""
+    @abstractmethod
+    def present(self) -> Any:
+        """Present the element to the user and return the result if applicable."""
+        pass
+
+class UIElement(Presentable):
+    """A generic UI element."""
+    def __init__(self, title: str = "", style: str = ""):
+        self.title = title
+        self.style = style
+
+class Option:
+    """A single choice within a Selection."""
+    def __init__(self, label: str, value: Any = None, callback: Optional[Callable] = None, description: str = ""):
+        self.label = label
+        self.value = value if value is not None else label
+        self.callback = callback
+        self.description = description
+
+class Selection(UIElement):
+    """Abstract concept of providing options for a user to choose from."""
+    def __init__(self, title: str = "", style: str = ""):
+        super().__init__(title, style)
+        self.options: List[Union[Option, 'Selection']] = []
+    
+    @abstractmethod
+    def add_option(self, label: str, value_or_callback: Any = None, description: str = ""):
+        """Add a single option to the selection."""
+        pass
+
+    @abstractmethod
+    def add_submenu(self, label: str, submenu: 'Selection', behavior: str = "push"):
+        """Add a nested selection (submenu). behavior can be 'push' or 'inline'."""
+        pass
+
+    @abstractmethod
+    def run(self, loop: bool = True) -> Any:
+        """Start the interaction loop."""
+        pass

ppui/core.py

@@ -0,0 +1,316 @@
+import shutil
+import subprocess
+import sys
+import uuid
+from typing import Optional, Dict, Any, List, Callable, Union
+
+from rich.console import Console
+from rich.panel import Panel
+from .base import Selection, Option, UIElement
+
+# Shared console instance for all Rich output
+console = Console()
+
+class Menu(Selection):
+    """
+    TUI implementation of the abstract Selection concept.
+    Encapsulates state management, boilerplate loops, and UI logic.
+    """
+    def __init__(self, title: str, style: str = "bold blue"):
+        super().__init__(title, style)
+        self.callbacks: Dict[str, Callable] = {}
+        self._items: List[Dict[str, Any]] = []
+
+    def add_option(self, label: str, value_or_callback: Any = None, description: str = ""):
+        """
+        Adds a menu option. 
+        If a callable is passed, it's stored as a callback and executed automatically in run().
+        If a string/value is passed, run() returns it upon selection.
+        """
+        if callable(value_or_callback):
+            action_id = f"cb_{uuid.uuid4().hex[:8]}"
+            self.callbacks[action_id] = value_or_callback
+            self._items.append({"title": label, "value": action_id, "description": description})
+        else:
+            self._items.append({"title": label, "value": value_or_callback, "description": description})
+
+    def add_item(self, label: str, action_or_callback: Any):
+        """Backward compatibility alias for add_option."""
+        self.add_option(label, action_or_callback)
+
+    def add_submenu(self, label: str, submenu: Selection, behavior: str = "push"):
+        """
+        Adds a nested selection. 
+        'push': Standard drill-down (opens a new menu).
+        'inline': Flattens submenu options into the current menu with indentation.
+        """
+        if behavior == "push":
+            self.add_option(label, lambda: submenu.run())
+        elif behavior == "inline":
+            # For inline, we store a reference to the submenu object
+            # and handle it during formatting in the run loop.
+            self._items.append({
+                "title": label, 
+                "value": submenu, 
+                "behavior": "inline", 
+                "is_submenu": True,
+                "expanded": False
+            })
+
+    def add_back_item(self, label: str = "[Back]"):
+        """Convenience method to add a standard Back option."""
+        self.add_option(label, "back")
+
+    def add_quit_item(self, label: str = "[Quit]"):
+        """Convenience method to add a standard Quit option."""
+        self.add_option(label, "quit")
+
+    def _get_flattened_items(self) -> List[Dict[str, Any]]:
+        """Flatten inline submenus if they are expanded."""
+        flat_list = []
+        for item in self._items:
+            flat_list.append(item)
+            if item.get("is_submenu") and item.get("behavior") == "inline" and item.get("expanded"):
+                submenu = item["value"]
+                # Recursively get items from submenu
+                sub_items = submenu._get_flattened_items() if isinstance(submenu, Menu) else []
+                for sub_item in sub_items:
+                    indented_item = sub_item.copy()
+                    indented_item["title"] = f"  {sub_item['title']}"
+                    flat_list.append(indented_item)
+        return flat_list
+
+    def _get_callback(self, action_id: str) -> Optional[Callable]:
+        """Resolve a callback ID, searching through inline submenus if necessary."""
+        if action_id in self.callbacks:
+            return self.callbacks[action_id]
+        
+        # Search in inline submenus
+        for item in self._items:
+            if item.get("is_submenu") and item.get("behavior") == "inline":
+                submenu = item["value"]
+                if isinstance(submenu, Menu):
+                    cb = submenu._get_callback(action_id)
+                    if cb:
+                        return cb
+        return None
+
+    def run(self, loop: bool = True) -> Any:
+        """
+        Starts the interactive menu interaction.
+        Returns the selected value (or 'quit'/'back' for standard items).
+        """
+        while True:
+            console.print(Panel(self.title, style=self.style))
+            
+            # Flatten items for display (handles inline expansion)
+            display_items = self._get_flattened_items()
+            
+            choices = format_menu_choices(display_items, title_field="title", value_field="value")
+            selection = prompt_toolkit_menu(choices)
+            
+            if selection is None: # Esc or Ctrl-C
+                return "quit"
+
+            # Handle inline submenu toggle
+            if isinstance(selection, Menu):
+                for item in self._items:
+                    if item.get("value") == selection:
+                        item["expanded"] = not item.get("expanded")
+                        break
+                continue
+
+            # Execute callback if it exists (resolving via hierarchy)
+            callback = self._get_callback(str(selection))
+            if callback:
+                res = callback()
+                if not loop:
+                    return selection # Return the ID that triggered the callback
+                continue
+            
+            # Standard navigation handling
+            if selection in ["quit", "exit"]:
+                return "quit"
+            if selection == "back":
+                return "back"
+                
+            if not loop:
+                return selection
+
+    def present(self) -> Any:
+        """Presentable implementation."""
+        return self.run()
+
+def prompt_yes_no(message: str, default: bool = False) -> bool:
+    """Standardize yes/no confirmation prompts."""
+    suffix = "[Y/n]" if default else "[y/N]"
+    while True:
+        choice = input(f"{message} {suffix}: ").strip().lower()
+        if choice == "":
+            return default
+        if choice in {"y", "yes"}:
+            return True
+        if choice in {"n", "no"}:
+            return False
+        console.print("[yellow]Please enter y or n.[/yellow]")
+
+def copy_to_clipboard(text: str) -> bool:
+    """Copy text to the system clipboard across different platforms."""
+    try:
+        if shutil.which("pbcopy"):
+            subprocess.run(["pbcopy"], input=text, text=True, check=True)
+            return True
+        elif shutil.which("xclip"):
+            subprocess.run(["xclip", "-selection", "clipboard"], input=text, text=True, check=True)
+            return True
+        elif shutil.which("xsel"):
+            subprocess.run(["xsel", "--clipboard", "--input"], input=text, text=True, check=True)
+            return True
+    except Exception:
+        pass
+    return False
+
+def prompt_toolkit_menu(choices, style=None, hotkeys=None, default_idx=0):
+    """Interactive selection menu supporting arrow keys and immediate hotkeys."""
+    from prompt_toolkit.key_binding import KeyBindings
+    from prompt_toolkit.application import Application
+    from prompt_toolkit.layout import Layout
+    from prompt_toolkit.layout.containers import Window, HSplit
+    from prompt_toolkit.layout.controls import FormattedTextControl
+    
+    idx = max(0, min(default_idx, len(choices) - 1)) if choices else 0
+    kb = KeyBindings()
+
+    @kb.add('up')
+    def _(event):
+        nonlocal idx
+        idx = (idx - 1) % len(choices)
+
+    @kb.add('down')
+    def _(event):
+        nonlocal idx
+        idx = (idx + 1) % len(choices)
+
+    @kb.add('enter')
+    def _(event):
+        event.app.exit(result=choices[idx].value)
+
+    @kb.add('escape')
+    @kb.add('c-c')
+    def _(event):
+        event.app.exit(result=None)
+
+    def make_hotkey_handler(h_val):
+        keys = list(str(h_val))
+        @kb.add(*keys)
+        def _(event):
+            for choice in choices:
+                clean_title = choice.title.strip().lower()
+                title_prefix = clean_title.split('.')[0].strip().lstrip('0')
+                h_prefix = str(h_val).lstrip('0')
+                
+                if clean_title.startswith(f"{h_val}."):
+                    event.app.exit(result=choice.value)
+                    return
+                if title_prefix == h_prefix and title_prefix != "":
+                    event.app.exit(result=choice.value)
+                    return
+                if str(choice.value) == str(h_val):
+                    event.app.exit(result=choice.value)
+                    return
+        return _
+
+    if not hotkeys:
+        hotkeys = []
+        for choice in choices:
+            title = choice.title.strip()
+            if '.' in title:
+                prefix = title.split('.')[0].strip().lower()
+                if prefix:
+                    hotkeys.append(prefix)
+                    if prefix.isdigit() and prefix.startswith('0') and prefix != '0':
+                        hotkeys.append(prefix.lstrip('0'))
+        if not hotkeys:
+            hotkeys = [str(i) for i in range(1, 10)] + ['q', 'b']
+    
+    seen = set()
+    unique_hotkeys = []
+    for h in hotkeys:
+        if h not in seen:
+            unique_hotkeys.append(h)
+            seen.add(h)
+
+    for h in unique_hotkeys:
+        make_hotkey_handler(h)
+
+    def get_text():
+        result = []
+        for i, choice in enumerate(choices):
+            if i == idx:
+                result.append(('class:selected', f" » {choice.title}\n"))
+            else:
+                result.append(('', f"   {choice.title}\n"))
+        return result
+
+    layout = Layout(HSplit([
+        Window(content=FormattedTextControl(get_text)),
+    ]))
+
+    from prompt_toolkit.styles import Style
+    if not style:
+        style = Style([('selected', 'fg:#cc9900')])
+
+    app = Application(layout=layout, key_bindings=kb, style=style, full_screen=False)
+    return app.run()
+
+def format_menu_choices(items: List[Any], title_field: Optional[str] = None, value_field: Optional[str] = None) -> List[Any]:
+    """Prepare a list of items for `prompt_toolkit_menu` by adding index numbers and hotkeys."""
+    import questionary
+    
+    special_keywords = {
+        "quit": "q", "[quit]": "q", "(q) [quit]": "q", "q": "q",
+        "back": "b", "[back]": "b", "(b) [back]": "b", "b": "b",
+        "menu": "m", "[menu]": "m", "return to menu": "m"
+    }
+    
+    regular_items = []
+    special_items = []
+    
+    for item in items:
+        title = ""
+        if isinstance(item, dict):
+            if title_field: title = str(item.get(title_field))
+            elif "title" in item: title = str(item["title"])
+            else: title = str(item)
+        else:
+            title = str(item)
+            
+        lower_title = title.strip().lower()
+        if lower_title in special_keywords:
+            special_items.append((item, special_keywords[lower_title]))
+        else:
+            regular_items.append(item)
+            
+    pad = len(str(len(regular_items)))
+    choices = []
+    
+    for i, item in enumerate(regular_items, 1):
+        idx_str = str(i).zfill(pad)
+        if isinstance(item, dict):
+            title = item.get(title_field) if title_field else item.get("title", str(item))
+            value = item.get(value_field) if value_field else item.get("value", item)
+        else:
+            title = str(item)
+            value = item
+        choices.append(questionary.Choice(f"{idx_str}. {title}", value=value))
+        
+    for item, key in special_items:
+        if isinstance(item, dict):
+            title = item.get(title_field) if title_field else item.get("title", str(item))
+            value = item.get(value_field) if value_field else item.get("value", item)
+        else:
+            title = str(item)
+            value = item
+        choices.append(questionary.Choice(f"{' ' * (pad - 1)}{key}. {title}", value=value))
+        
+    return choices

ppui-2026.1.20.2.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: ppui
+Version: 2026.1.20.2
+Summary: Python Process User Intent: A high-level abstract UI system (TUI, Web, Voice)
+Project-URL: Homepage, https://github.com/nextoken/pas
+Author-email: Next Token <nextoken@gmail.com>
+License: MIT
+Requires-Python: >=3.8
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# PPUI: Python Process User Intent 🎭
+
+A high-level abstract UI system for Python scripts. 
+
+PPUI (pronounced "pui") is the Python implementation of the **PUI** (**Process User Intent**) philosophy.
+
+The goal isn't just to "draw a menu"—it's to capture what the user wants to do next. Whether that intent is captured via a terminal hotkey, a web click, or a voice command, the script's logic remains the same. 
+
+*PPUI: Because your scripts should care about what you want, not just how you say it.*
+
+## Features
+- **High-level Abstractions**: Use concepts like `Selection` and `Input` without caring about the rendering engine.
+- **TUI Implementation**: Professional, hotkey-driven terminal menus.
+- **Submenu Support**: Nested selections with `push` (drill-down) or `inline` (expandable) behaviors.
+- **Rich Integration**: Full support for Rich-formatted output and panels.
+
+## Installation
+
+```bash
+pip install ppui
+```
+
+## Usage
+
+### High-Level Menu Class
+
+The `Menu` class provides a declarative way to build interactive loops with callback support.
+
+```python
+from ppui import Menu
+
+def run_setup():
+    print("Running setup...")
+
+def main():
+    menu = Menu("Project Manager", style="bold green")
+    menu.add_option("Setup Project", run_setup)
+    menu.add_option("View Dashboard", "view_dash")
+    
+    # Submenu support
+    advanced = Menu("Advanced Settings")
+    advanced.add_option("DNS Config", lambda: print("Configuring DNS..."))
+    menu.add_submenu("Advanced...", advanced, behavior="push")
+    
+    menu.add_back_item() 
+    menu.add_quit_item()
+    
+    selection = menu.run()
+```

ppui-2026.1.20.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+ppui/__init__.py,sha256=cq47TICGZ34Vj2jEHnH19Xi8K-9oA_HdMJU7gTTKkIk,424
+ppui/base.py,sha256=BGjaE7i188vIu3K3QHnlo0tw6vgfVZydhlgeWiWZx2c,1711
+ppui/core.py,sha256=gJAEF65Ly-qSmYURtD1xsZ7AduTz1WErv6a4Yz9J9Gs,11760
+ppui-2026.1.20.2.dist-info/METADATA,sha256=idFznS6IKvRi0-ebh1fvkFfe3gBZkc_P8gmvyhMo3Uk,2022
+ppui-2026.1.20.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+ppui-2026.1.20.2.dist-info/RECORD,,

ppui-2026.1.20.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any