luvmagitoolkits 0.1.0

A modular Python toolkit with a decorator-driven Textual TUI framework.

luvmagiToolKits

luvmagiToolKits is a modular Python toolkit. The first release focuses on decotextual, a decorator-driven helper layer for building small Textual-based tool panels quickly.

The repository also contains placeholder modules for future toolkit areas such as database, dataframe, excel, image, and general utilities. At the current stage, decotextual is the production-ready part of the package.

Installation

Install the base package:

pip install luvmagitoolkits

Install the Textual runtime if you want to launch the TUI:

pip install "luvmagitoolkits[tui]"

Install every optional dependency:

pip install "luvmagitoolkits[all]"

What decotextual Provides

• A class decorator to register tools into a navigable tree.
• A method decorator to define labels, descriptions, and placeholders.
• A simple Linear(...) helper for select-style choices.
• A ready-to-run Textual application launcher with run_tui().

Quick Start

from pathlib import Path

from luvmagitoolkits.decotextual import Linear, register_tool, run_tui, tool_method


@register_tool(category="File Tools", tool_name="File Utilities")
class FileTool:
    @tool_method(
        name="Read File",
        description="Read a file and return the first N lines",
        placeholders={
            "file_path": "Full path, e.g. ./demo.txt",
            "tags": "One tag per line, or comma-separated",
        },
    )
    def read_file(self, file_path: Path, line_count: int = 20, tags: list | None = None):
        print(f"Reading {file_path} - first {line_count} lines")
        if tags:
            print(f"Tags: {tags}")
        return "Done"

    @tool_method(
        name="Batch Rename",
        description="Batch rename files in a directory",
        placeholders={"directory": "Target directory path"},
    )
    def batch_rename(
        self,
        directory: Path,
        prefix: str = "file_",
        mode: Linear = Linear("Sequential", "Timestamp", "MD5"),
    ):
        print(f"Scanning: {directory}")
        print(f"Prefix: {prefix}, Mode: {mode}")
        return "Rename complete"


if __name__ == "__main__":
    run_tui()

Release Status

• Package version: 0.1.0
• Stability: alpha
• Recommended audience: early adopters and internal experimentation

Roadmap

• Expand the decotextual examples and tests.
• Add module-specific documentation under docs/.
• Gradually fill in the database, dataframe, excel, image, and utils modules.

Project Links

• Repository: https://github.com/luvmagi/luvmagiToolKits
• Issues: https://github.com/luvmagi/luvmagiToolKits/issues