Metadata-Version: 2.4
Name: pyzup
Version: 0.1.2
Summary: Reusable upload handler for PDFs, DOCX, PPTX, ZIPs
Author: Punit Tripathi, Mohd. Amir
Author-email: tripathi.punit@proton.me, amir.zilli@gmail.com
License: MIT
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Werkzeug==3.1.3
Requires-Dist: loguru==0.7.3
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🗂️ PYZUP

**PYZUP** is a lightweight, reusable Python module designed to streamline file uploads in document-based applications. It supports single and multiple file uploads of:

- 📄 PDF (`.pdf`)
- 📊 PowerPoint (`.pptx`)
- 📝 Word (`.docx`)
- 📈 Excel (`.xlsx`)
- 🗜️ ZIP archives containing the above formats

PYZUP handles validation, safe extraction of ZIPs, automatic logging, and returns structured responses ideal for web APIs.

---

## ✅ Features

- Upload **single or multiple files**
- Validate ZIPs (must contain at least one allowed file)
- Logs **disallowed or corrupt files** cleanly
- Automatically creates target directories
- Daily **rotating logs** (JSON compressed + console)
- Structured response with `"success"` and `"error"` lists

---

## 🧩 How to Use

```python
from werkzeug.datastructures import FileStorage
from pathlib import Path
from pyzup import handle_uploaded_file

file_objs = request.files.getlist("files")  # Flask example
result = handle_uploaded_file(file_objs, Path("target_folder"))

if not result["success"]:
    return jsonify({"error": "No valid files processed", "details": result["error"]}), 415

return jsonify(result), 200
```

---

## 📥 Example Response

```json
{
  "success": [
    {"filename": "report.pdf", "message": "report.pdf uploaded successfully."},
    {"filename": "slides.zip", "message": "ZIP extracted successfully."}
  ],
  "error": [
    {"filename": "malicious.exe", "message": "Allowed types: docx, pdf, pptx, xlsx, zip."}
  ]
}
```

---

## ⚙️ Flask Integration Example

```python
from flask import Flask, request, jsonify
from pathlib import Path
from datetime import datetime
from pyzup import handle_uploaded_file
from loguru import logger

app = Flask(__name__)
UPLOAD_ROOT = Path("uploaded_docs")

@app.route("/", methods=["POST"])
def upload():
    files = request.files.getlist("files")
    if not files:
        return jsonify({"error": "No file part in request."}), 400

    folder = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
    target_dir = UPLOAD_ROOT / folder
    result = handle_uploaded_file(files, target_dir)

    return jsonify(result), 200
```

---

## 📁 Logging

Logs are stored in `upload_logs/`:
- Daily log files: `app_YYYYMMDD.log.zip`
- Console: logs shown at INFO level
- File logs: full tracebacks and debugging info

---

## 🔒 Validation Rules

- ✅ Allowed file types: `.pdf`, `.docx`, `.pptx`, `.xlsx`, `.zip`
- ✅ ZIP must contain at least one allowed file
- ⚠️ Unsupported ZIP contents are ignored and logged
- ❌ Empty filenames or invalid formats are rejected

---

## 👨‍💻 Authors

- Punit Tripathi ([tripathi.punit@proton.me](mailto:tripathi.punit@proton.me))
- Mohd. Amir ([amir.zilli@gmail.com](mailto:amir.zilli@gmail.com))

---

## 📜 License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

---

## 📌 Status

✅ Actively maintained, production-ready, and easy to integrate into Flask apps or other backends.
