Metadata-Version: 2.4
Name: xfep-pdf
Version: 0.1.0
Summary: Generación de PDF para representación impresa de CPE — Facturación Electrónica Perú
Project-URL: Homepage, https://github.com/Xpertik/xfep-pdf
Project-URL: Repository, https://github.com/Xpertik/xfep-pdf
Project-URL: Issues, https://github.com/Xpertik/xfep-pdf/issues
Project-URL: Documentation, https://github.com/Xpertik/xfep-pdf#readme
Author-email: Jhonatan Mosquera Tabra <jhonatanmt83@gmail.com>
Maintainer-email: Jhonatan Mosquera Tabra <jhonatanmt83@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cpe,facturacion-electronica,pdf,peru,qr,reportlab,sunat,weasyprint
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Natural Language :: Spanish
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Printing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: jinja2>=3.1
Requires-Dist: segno>=1.6
Requires-Dist: xfep-models>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: xfep-models>=0.1.0; extra == 'dev'
Provides-Extra: reportlab
Requires-Dist: pillow>=10.0; extra == 'reportlab'
Requires-Dist: reportlab>=4.0; extra == 'reportlab'
Provides-Extra: weasyprint
Requires-Dist: weasyprint>=62.0; extra == 'weasyprint'
Description-Content-Type: text/markdown

# xfep-pdf

Generación de **representación impresa en PDF** para Comprobantes de Pago Electrónicos — Perú (SUNAT).

Parte del [ecosistema XFEP](https://github.com/Xpertik). Depende de [`xfep-models`](https://github.com/Xpertik/xfep-models).

Genera el formato A4 estándar SUNAT con QR incluido, a partir de cualquier documento `xfep-models` (Factura, Boleta, Notas de Crédito/Débito, Guía de Remisión).

## Instalación

`xfep-pdf` soporta dos motores de renderizado. Instalá **uno** como extra:

```bash
# WeasyPrint (recomendado — mejor calidad tipográfica)
pip install "xfep-pdf[weasyprint]"

# ReportLab (fallback — no requiere dependencias del sistema)
pip install "xfep-pdf[reportlab]"
```

## Uso

```python
from xfep.pdf import PdfGenerator
from xfep.models import Invoice, Company

company = Company(
    ruc="20123456789",
    razon_social="MI EMPRESA S.A.C.",
    direccion="Av. Principal 123, Lima",
    # ... demás campos
)

invoice = Invoice(
    # ... completar con datos del comprobante
)

gen = PdfGenerator()
pdf_bytes: bytes = gen.generate(
    document=invoice,
    company=company,
    correlativo=42,
    logo=None,  # opcional: bytes PNG/JPEG
)

# Guardar o servir
with open("F001-00000042.pdf", "wb") as f:
    f.write(pdf_bytes)
```

## Documentos soportados

| Modelo | Label | Template |
|--------|-------|----------|
| `Invoice` | FACTURA ELECTRÓNICA | `invoice.html` |
| `Boleta` | BOLETA DE VENTA ELECTRÓNICA | `invoice.html` (compartido) |
| `CreditNote` | NOTA DE CRÉDITO ELECTRÓNICA | `credit_note.html` |
| `DebitNote` | NOTA DE DÉBITO ELECTRÓNICA | `debit_note.html` |
| `DispatchGuide` | GUÍA DE REMISIÓN ELECTRÓNICA | `dispatch.html` |

## Características

- **Motor dual** — WeasyPrint (prioritario) con fallback a ReportLab.
- **QR embebido** — Generado según especificación SUNAT (RUC, tipo, serie, correlativo, IGV, total, fecha, cliente).
- **Templates Jinja2** — Personalizables; `autoescape=True` por defecto.
- **Logo opcional** — Acepta bytes PNG/JPEG; se embebe como base64.
- **Cálculos incluidos** — Subtotal, IGV (18%), ISC, ICBPER, total por línea y documento.
- **Formato A4 estándar** — Cumple lineamientos SUNAT para representación impresa.

## API

### `PdfGenerator.generate`

```python
PdfGenerator().generate(
    document: Invoice | Boleta | CreditNote | DebitNote | DispatchGuide,
    company: Company,
    *,
    correlativo: int = 1,
    logo: bytes | None = None,
) -> bytes
```

Retorna los bytes del PDF generado. Lanza `ValueError` si el tipo de documento no es soportado.

### Helpers de QR

```python
from xfep.pdf import build_qr_string, generate_qr_base64

qr_text = build_qr_string(invoice, company, correlativo=42, total_igv="180.00", total_venta="1180.00")
qr_b64 = generate_qr_base64(qr_text)
```

## Stack

- **Python** >= 3.13
- **Jinja2** >= 3.1
- **segno** >= 1.6 (generación de QR)
- **xfep-models** >= 0.1.0
- **Extras**: `weasyprint>=62.0` o `reportlab>=4.0 + pillow>=10.0`
- **Build**: Hatchling
- **Tests**: pytest

## Desarrollo

```bash
git clone https://github.com/Xpertik/xfep-pdf.git
cd xfep-pdf

python3.13 -m venv .venv
source .venv/bin/activate
pip install -e "../xfep-models"
pip install -e ".[dev,weasyprint]"

pytest -v
```

## Licencia

Apache License 2.0 — ver [LICENSE](LICENSE).
