Metadata-Version: 2.4
Name: toolvix
Version: 0.1.1
Summary: Simple dynamic file, PDF, and image automation tools for Python
Author-email: "A.Preetam krishna" <preetam.200729@gmail.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: Pillow>=10.0
Requires-Dist: pypdf>=4.0
Requires-Dist: pdf2docx>=0.5.6
Requires-Dist: PyMuPDF>=1.24
Requires-Dist: python-pptx>=0.6.23
Requires-Dist: cryptography>=42.0
Provides-Extra: windows
Requires-Dist: pywin32>=306; extra == "windows"

# Toolvix

Toolvix is a Python library for simple file, PDF, PowerPoint, Word, and image automation.

Most functions can automatically discover matching files in the **current working folder**. For predictable pipelines, functions also accept a `source` value containing a path or a list of paths returned by another Toolvix function.

## Installation

```bash
pip install toolvix
```

For PowerPoint/Word to PDF conversion on Windows:

```bash
pip install "toolvix[windows]"
```

Microsoft PowerPoint and/or Microsoft Word must also be installed for the corresponding conversion.

## Quick start

```python
from toolvix import *

pdfMerge()
pdfExtract([1, 2])
pdfProtect(password="StrongPassword123!")

imageTopdf()
imageResize(1920, 1080)
imageWatermark("PREETAM")
imageCompressor(1)

fileEncrypt()
fileDecrypt()
```

## API reference

The table intentionally shows the **complete callable syntax**. Parameter explanations are kept on the individual function documentation pages so the main API table remains compact.

| # | Function syntax | Automatic input | Output | Details |
|---:|---|---|---|---|
| 1 | `fileEncrypt(source=None)` | All non-`.encrypted` files | Encrypted `.encrypted` files | [Function details](docs/functions/fileEncrypt.md) |
| 2 | `fileDecrypt(source=None)` | All `.encrypted` files | Decrypted original files | [Function details](docs/functions/fileDecrypt.md) |
| 3 | `pdfMerge(output_file="Merged.pdf", source=None)` | All PDFs | One merged PDF | [Function details](docs/functions/pdfMerge.md) |
| 4 | `pdfExtract(pages, output_file="extracted.pdf", source=None)` | First PDF | Extracted PDF | [Function details](docs/functions/pdfExtract.md) |
| 5 | `pdfProtect(output_file="protected.pdf", password="12345", source=None)` | First PDF | Protected PDF | [Function details](docs/functions/pdfProtect.md) |
| 6 | `pdfToword(output_file=None, source=None)` | All PDFs | DOCX file(s) | [Function details](docs/functions/pdfToword.md) |
| 7 | `pdfToppt(output_file=None, source=None)` | All PDFs | PPTX file(s) | [Function details](docs/functions/pdfToppt.md) |
| 8 | `pptTopdf(output_file=None, source=None)` | All PPTX files | PDF file(s) | [Function details](docs/functions/pptTopdf.md) |
| 9 | `wordTopdf(output_file=None, source=None)` | All DOCX files | PDF file(s) | [Function details](docs/functions/wordTopdf.md) |
| 10 | `imageTopdf(output_file="photos.pdf", source=None)` | All supported images | One PDF | [Function details](docs/functions/imageTopdf.md) |
| 11 | `imageResize(width=1920, height=1080, source=None)` | All supported images | Resized image(s) | [Function details](docs/functions/imageResize.md) |
| 12 | `imageWatermark(watermarkText="PREETAM", textSize=100, transparency=45, angle=25, source=None)` | All supported images | Watermarked image(s) | [Function details](docs/functions/imageWatermark.md) |
| 13 | `imageCompressor(targetSizeMB=1, source=None)` | All supported images | Compressed JPG(s) | [Function details](docs/functions/imageCompressor.md) |
| 14 | `pdfToimage(source=None)` | All PDFs | Page PNG image(s) | [Function details](docs/functions/pdfToimage.md) |

## Nested functions and chaining

Toolvix supports deterministic function pipelines. A function can pass its returned path or list of paths directly into another function.

### Merge → Word

```python
pdfToword(pdfMerge())
```

This converts **only the PDF created by `pdfMerge()`**. It does not convert every PDF in the working folder.

### Merge → PowerPoint

```python
pdfToppt(pdfMerge())
```

### Merge → extract pages

```python
pdfExtract([1, 2, 5], source=pdfMerge())
```

### Merge → protect

```python
pdfProtect(password="StrongPassword123!", source=pdfMerge())
```

### Merge → images

```python
pdfToimage(pdfMerge())
```

### Resize → watermark → PDF

```python
imageTopdf(
    source=imageWatermark(
        "PREETAM",
        source=imageResize(1600, 1200)
    )
)
```

### Read the complete chaining guide

See [Nested functions and chaining](docs/nesting.md), which documents compatible nesting patterns, automatic discovery versus pipeline input, return-value rules, and examples.

## Input behavior

There are two modes.

### 1. Automatic discovery

```python
pdfToword()
```

All PDFs in the current working folder are converted.

### 2. Explicit pipeline input

```python
merged = pdfMerge()
pdfToword(merged)
```

Only the PDF returned by `pdfMerge()` is converted.

The same `source` mechanism is available throughout the API. This prevents generated results from accidentally causing unrelated files in the working folder to be processed.

## Return values

- One selected output file → `pathlib.Path`
- Multiple output files → `list[pathlib.Path]`
- No matching input → `None`

These return values are what make nested calls possible.

## Output folders

Toolvix keeps generated files in separate folders, including:

- `merged pdf`
- `extracted pdfs`
- `protected pdfs`
- `converted word files`
- `converted ppt files`
- `converted pdf files`
- `converted pdfs`
- `resized images`
- `watermarked images`
- `compressed images`
- `converted images`

## Supported image formats

Image functions support:

- JPG / JPEG
- PNG
- WEBP
- BMP

## Notes

- Run your script from the folder containing the files you want Toolvix to discover.
- When `source` is supplied, only the supplied files are processed.
- Office conversions require the corresponding Microsoft Office application on Windows.
- `pdfToword()` requires `pdf2docx`.
- `pdfToppt()` and `pdfToimage()` use PyMuPDF.
- Do not store passwords or sensitive files in the working folder when using `fileEncrypt()`.

## Documentation hosting

The repository contains detailed Markdown pages and a standalone HTML documentation site under `docs/`.

The `Details` links in the API table are repository-relative documentation links. To make those links open as independent web pages directly from the PyPI description, the `docs/` site must be hosted (for example with GitHub Pages or Read the Docs). Once a real documentation URL is available, it should be added to `[project.urls]` in `pyproject.toml` and the table links can be changed to those absolute URLs.

A documentation URL should **not** be invented before the site is actually hosted.
