English · 简体中文 · 日本語 · 한국어

decoui

Turn annotated Python methods into native desktop tools people can actually use.

Decorator-driven GUI framework for Python · Built with PySide6

decoui turns function signatures into forms, executions into live logs, and every run into a traceable record. You keep writing Python business logic; decoui supplies the Qt window, background execution, history, replay, settings, and help system.

What decoui does for you

Help and localization, built in

Turn docstrings into user-facing help

Document the method once. decoui automatically collects docstrings into searchable, navigable help pages—complete with summaries, parameters, return values, exceptions, and cross-references.

Make every user feel at home

One interface, many languages. Select the interface language and provide application catalogues for your own labels, fields, descriptions, and help content—without rebuilding the UI.

More than a generated form

• Themes — Four built-in looks: Light, Cockpit, Mission Control, and Industrial 1980s. Extend or replace them with JSON, and switch themes without interrupting running tools.
• Internationalization (i18n) — decoui ships its own interface catalogues. Your tool labels, fields, descriptions, and help content can use separate application catalogues.
• Collected help — Build summaries, parameter tables, return values, and error documentation from docstrings. Add long-form Markdown and cross-reference other help pages.
• Reliable execution — Run tools on background threads with progress reporting, timeouts, cancellation, and streamed child-process output.
• History and replay — Persist every run in SQLite, filter the history, inspect full logs, and restore an earlier parameter snapshot.

Start in 30 seconds

pip install decoui

Requires Python 3.10 or later. decoui depends on the smaller PySide6-Essentials package by default, without pulling in the complete PySide6-Addons payload.

import logging

from decoui import gui_main, tool, toolset


@toolset(label="Text Tools", tags=["text"])
class TextTools:
    @tool(
        label="Count Characters",
        description="Count characters, words, and lines.",
        placeholders={"content": "Paste text here..."},
    )
    def count(self, content: str = "") -> None:
        words = len(content.split())
        logging.info("%d chars / %d words", len(content), words)


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

Run the file. gui_main() discovers every @toolset in the caller's namespace and builds the complete application around it.

python app.py

Types become forms

Add completions, cascade, and defaults for autocomplete, dependent fields, and runtime defaults. The underlying methods remain ordinary Python and can still be called and tested without the GUI.

Documentation

The detailed material has moved out of this README so you can jump directly to the guide you need:

• Complete API and behavior reference — decorators, type mapping, form assistance, themes, storage, history, and more
• Startup lifecycle — initialization order, loading data, and failure handling
• Application translation — localizing tool text and long-form help
• Help authoring — docstrings, Markdown, and cross-references
• Cancellation and child processes — implementing Stop, timeouts, and cleanup correctly
• Design and implementation — module structure, execution engine, storage, and UI architecture

For a complete example covering every supported feature, explore src/decoui/example/ and run:

python -m decoui.example

Where it fits

Data processors, operations utilities, batch-job launchers, internal productivity tools, and Python scripts intended for non-developers—especially when the business logic already exists and only needs a reliable desktop entry point.

decoui is currently in Alpha. Please share real-world issues and feedback through GitHub Issues.

License

MIT