Metadata-Version: 2.4
Name: luvmagitoolkits
Version: 0.1.2
Summary: A modular Python toolkit with JSON diff utilities and optional Textual and WBS helpers.
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
Project-URL: Documentation, https://github.com/luvmagi/luvmagiToolKits#readme
Author-email: luvmagi <luvmagi@outlook.com>
License: MIT
License-File: LICENSE
Keywords: diff,json,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
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: rich>=15.0.0; extra == 'all'
Requires-Dist: textual>=8.2.4; extra == 'all'
Requires-Dist: toml>=0.10.2; extra == 'all'
Requires-Dist: xlwings>=0.33.16; 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: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pytest>=8.4.2; extra == 'dev'
Requires-Dist: twine>=6.1.0; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.5; extra == 'excel'
Requires-Dist: pandas>=2.3.3; extra == 'excel'
Requires-Dist: xlwings>=0.33.16; extra == 'excel'
Provides-Extra: image
Requires-Dist: pillow>=12.2.0; extra == 'image'
Provides-Extra: serialization
Requires-Dist: pyyaml>=6.0.3; extra == 'serialization'
Provides-Extra: tui
Requires-Dist: rich>=15.0.0; 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'
Provides-Extra: wbs
Requires-Dist: pandas>=2.3.3; extra == 'wbs'
Requires-Dist: xlwings>=0.33.16; extra == 'wbs'
Description-Content-Type: text/markdown

# luvmagiToolKits

`luvmagiToolKits` is a modular Python toolkit.

The current public release includes:

- `json_diff`: compare two JSON-serializable documents and write JSON or Markdown reports
- `decotextual`: a decorator-driven helper layer for building small Textual-based tool panels quickly
- `wbs`: WBS-oriented helpers that depend on the `wbs` extra

## Installation

Install the lightweight base package:

```bash
pip install luvmagitoolkits
```

The base install is intended for dependency-light modules such as `json_diff`.

Install the Textual TUI helpers:

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

Install the WBS helpers:

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

Install every optional dependency:

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

Upgrade the package:

```bash
pip install -U luvmagitoolkits
```

## What `json_diff` Provides

- Structured diffs for dictionaries, lists, and nested JSON-like payloads.
- Configurable array matching by key, inferred key, hash, or index.
- JSON and Markdown output writers with explicit `encoding` parameters.

## 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()`.

`run_tui()` requires the `tui` extra.

## 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.1`
- 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>
- Release guide: [docs/pypi-release.md](docs/pypi-release.md)
