Metadata-Version: 2.4
Name: handlemyfile
Version: 0.2.1
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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 :: Office/Business :: Office Suites
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
License-File: LICENSE
Summary: High-precision PDF to DOCX converter engine in pure Rust with Python bindings.
Keywords: pdf,docx,converter,word,rust,wasm,maturin
Author: HandleMyFile Contributors
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/handlemyfile/handlemyfile#readme
Project-URL: Homepage, https://github.com/handlemyfile/handlemyfile
Project-URL: Issues, https://github.com/handlemyfile/handlemyfile/issues
Project-URL: Repository, https://github.com/handlemyfile/handlemyfile

# HandleMyFile for Python

<div align="center">

[![PyPI Version](https://img.shields.io/pypi/v/handlemyfile.svg)](https://pypi.org/project/handlemyfile/)
[![Python Versions](https://img.shields.io/pypi/pyversions/handlemyfile.svg)](https://pypi.org/project/handlemyfile/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**Edge-native, high-precision PDF to DOCX converter engine in pure Rust with native PyO3 bindings.**  
Zero external Java, LibreOffice, or Poppler dependencies. Zero cloud egress.

</div>

---

## Why HandleMyFile for Python?

Most Python PDF-to-Word solutions suffer from critical operational drawbacks:
- They wrap heavy external applications like **LibreOffice / soffice** or **Java** runtimes, causing massive container bloat (500 MB+ Docker images) and high memory overhead.
- Or they rely on third-party SaaS cloud APIs, introducing data privacy risks, network latency, and recurring billing.

**HandleMyFile** embeds a pure Rust Document Layout Analysis (DLA) engine directly into Python as a native C-extension:

1. **Zero External Binary Dependencies**:  
   No `apt-get install libreoffice`, no Java JVM, no Poppler utilities. Just `pip install handlemyfile`.
2. **Lightning-Fast Native PyO3 Execution**:  
   Executes directly in-process at native compiled speed with minimal RAM consumption.
3. **Versatile Dual API (Bytes & Files)**:  
   Supports in-memory byte streaming `convert(pdf_bytes)` for high-throughput web frameworks (FastAPI, Flask, Django) as well as file-to-file conversion `convert_file(in_path, out_path)` for batch jobs.
4. **Clean OOXML Structure**:  
   Generates validated OpenXML Word documents with real paragraph hierarchies, styled headings, true tables (`<w:tbl>`), and dynamic page numbers (`<w:fldSimple w:instr="PAGE"/>`).

---

## Honest & Transparent Limitations

> [!WARNING]
> **Multi-Column (2-Column) Layouts are Under Active Development**
>
> While single-column documents (theses, academic reports, books, contracts, invoices, and standard forms) convert with high structural fidelity, **complex two-column documents** (such as dense IEEE/ACM papers or newspaper formats with straddling figures/tables) are a known current limitation. 
> 
> We are actively refining our recursive R-XY-Cut segmentation algorithm for multi-column split balancing in upcoming releases.

---

## Installation

```bash
pip install handlemyfile
```

---

## Usage

### 1. File-to-File Conversion

```python
import handlemyfile

# Simple 1-line conversion:
handlemyfile.convert_file("document.pdf", "output.docx")

# With real-time page progress callback:
def on_progress(current_page, total_pages, stage):
    print(f"Processing page {current_page}/{total_pages} [{stage}]")

handlemyfile.convert_file("large_document.pdf", "output.docx", on_progress=on_progress)
```

### 2. In-Memory Streaming (FastAPI / Flask Example)

Perfect for serverless functions, microservices, or web APIs where files shouldn't touch the disk:

```python
from fastapi import FastAPI, UploadFile, Response
import handlemyfile

app = FastAPI()

@app.post("/convert")
async def convert_pdf(file: UploadFile):
    pdf_bytes = await file.read()
    
    # 100% in-memory conversion:
    docx_bytes = handlemyfile.convert(pdf_bytes)
    
    return Response(
        content=docx_bytes,
        media_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        headers={"Content-Disposition": f"attachment; filename={file.filename.replace('.pdf', '.docx')}"}
    )
```

### 3. Granular Typed Exceptions

Handle protected or corrupted files gracefully:

```python
import handlemyfile

try:
    with open("secret_report.pdf", "rb") as f:
        docx_bytes = handlemyfile.convert(f.read())
except handlemyfile.PasswordProtectedError:
    print("Error: This PDF is encrypted or password-protected.")
except handlemyfile.InvalidPdfError:
    print("Error: The file is not a valid PDF document.")
except handlemyfile.CorruptPdfError as e:
    print(f"Error: Corrupted PDF stream: {e}")
except handlemyfile.EmptyDocumentError:
    print("Error: The document contains zero readable pages.")
except handlemyfile.HandleMyFileError as e:
    print(f"Conversion failed: {e}")
```

### 4. Standalone CLI

Installing via pip also provides a direct command-line tool:

```bash
handlemyfile input.pdf output.docx
```

---

## License

MIT © HandleMyFile Contributors

