Metadata-Version: 2.4
Name: luvmagitoolkits
Version: 0.1.0
Summary: A modular Python toolkit with a decorator-driven Textual TUI framework.
Project-URL: Homepage, https://github.com/luvmagi/luvmagiToolKits
Project-URL: Repository, https://github.com/luvmagi/luvmagiToolKits
Project-URL: Issues, https://github.com/luvmagi/luvmagiToolKits/issues
Author-email: luvmagi <luvmagi@outlook.com>
License: MIT
License-File: LICENSE
Keywords: decorators,terminal,textual,toolkit,tui,utilities
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: rich>=15.0.0
Provides-Extra: all
Requires-Dist: openpyxl>=3.1.5; extra == 'all'
Requires-Dist: pandas>=2.3.3; extra == 'all'
Requires-Dist: pillow>=12.2.0; extra == 'all'
Requires-Dist: psycopg2>=2.9.11; extra == 'all'
Requires-Dist: pyperclip>=1.11.0; extra == 'all'
Requires-Dist: pyyaml>=6.0.3; extra == 'all'
Requires-Dist: textual>=8.2.4; extra == 'all'
Requires-Dist: toml>=0.10.2; extra == 'all'
Provides-Extra: database
Requires-Dist: psycopg2>=2.9.11; extra == 'database'
Requires-Dist: pyyaml>=6.0.3; extra == 'database'
Provides-Extra: dataframe
Requires-Dist: pandas>=2.3.3; extra == 'dataframe'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.5; extra == 'excel'
Requires-Dist: pandas>=2.3.3; extra == 'excel'
Provides-Extra: image
Requires-Dist: pillow>=12.2.0; extra == 'image'
Provides-Extra: tui
Requires-Dist: textual>=8.2.4; extra == 'tui'
Provides-Extra: utils
Requires-Dist: pyperclip>=1.11.0; extra == 'utils'
Requires-Dist: pyyaml>=6.0.3; extra == 'utils'
Requires-Dist: toml>=0.10.2; extra == 'utils'
Description-Content-Type: text/markdown

# 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:

```bash
pip install luvmagitoolkits
```

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

```bash
pip install "luvmagitoolkits[tui]"
```

Install every optional dependency:

```bash
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

```python
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>
