decoui

Decorator-driven GUI framework for Python. Annotate your methods — decoui generates a full PySide6 desktop app automatically.

Features

• Zero UI code — decorate a class and its methods, call gui_main()
• Native type mapping — str, int, float, bool, list, dict, Enum → widgets automatically
• Async execution — every tool runs in a thread; stdout and logging are captured in real time
• Execution history — every run is persisted to SQLite with parameters, logs, and status
• Parallel tool tabs — keep multiple tool pages open and switch between running tasks
• Persistent layout — sidebar width is restored from the application database
• Replay — restore any past run's parameters with one click
• Light theme — clean built-in stylesheet, Consolas / 微软雅黑 / Meiryo font stack

Installation

pip install decoui

Requires Python 3.10+ and PySide6 6.6+.

Quick Start

import logging
from decoui import tool, toolset, gui_main

@toolset(label="Text Tools", tags=["text"])
class TextTools:

    @tool(label="Count Characters",
          description="Count chars, words and lines.",
          placeholders={"content": "Paste text here…"})
    def count(self, content: str = "") -> str:
        words = len(content.split())
        logging.info("words=%d", words)
        return f"{len(content)} chars / {words} words"

if __name__ == "__main__":
    gui_main(title="My Tools")

gui_main() auto-discovers every @toolset class in the caller's global scope — no explicit registration needed.

API Reference

@toolset

Applied to a class. Groups its @tool methods under one sidebar entry.

@toolset(
    label="CSV Tools",           # required — sidebar display name
    tags=["file", "batch"],      # optional — used by the tag filter bar
    description="...",           # optional — tooltip on hover in the sidebar
)
class CsvTools:
    ...

@tool

Applied to a method inside a @toolset class.

@tool(
    label="Merge Files",
    description="Merge multiple files into one.",
    placeholders={"files": "one path per line"},
    confirm=True,     # show confirmation dialog before running
    timeout=120,      # cancel after N seconds (None = unlimited)
)
def merge(self, files: list, output: str = "out.txt") -> str:
    ...

gui_main

gui_main(title="My App", db_path="~/.myapp/history.db")

Type → Widget Mapping

• Required parameters (no default) are marked with a red * in the form label.
• Optional[X] is unwrapped to X.
• Default values are pre-filled into widgets automatically.

pathlib.Path example

import pathlib
from decoui import tool, toolset

@toolset(label="File Tools")
class FileTools:

    @tool(label="File Info", placeholders={"path": "Select a file or folder…"})
    def file_info(self, path: pathlib.Path) -> None:
        import logging
        p = pathlib.Path(path)
        logging.info("size: %d bytes", p.stat().st_size)
        logging.info("resolved: %s", p.resolve())

Output & Logging

Tool methods can use print() and the standard logging module. Both are captured and rendered in the output console with colour coding:

Return values from tool methods are not displayed in the GUI. Use logging or print for any output you want users to see.

Tool Page Buttons

Execution History

Every run is stored in SQLite. The History panel (sidebar button) shows:

• Timestamp, tool name, status badge, duration
• Per-row checkboxes with Select All / Deselect All / Delete Selected
• Filter by tool, status, and time range
• Click any row to see the parameter snapshot
• Replay Params — restores that run's parameters to the tool's form
• View Full Log — opens the full log in a resizable window with level filters and search

History is stored at ~/.decoui/history.db by default. Override with db_path in gui_main().

Example

See src/decoui/example.py for a complete demo covering all supported widget types.

Run it with:

uv run python main.py
# or
python main.py