Metadata-Version: 2.4
Name: sinpapel-reports
Version: 0.2.0
Summary: Pluggable template-driven document generation (PDF overlay + DOCX) for the sinpapel ecosystem.
Author-email: Julio Adrián <jadrian.s@gmail.com>
License-Expression: GPL-3.0-or-later
Keywords: django,pdf,docx,report,document-generation,overlay,sinpapel
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=5.0
Requires-Dist: sinpapel>=0.7.0
Requires-Dist: PyPDF2>=3.0
Requires-Dist: reportlab>=4.4
Requires-Dist: docxtpl
Provides-Extra: drf
Requires-Dist: djangorestframework>=3.14; extra == "drf"
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: pytest-django>=4.12; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: django-stubs>=5.0; extra == "dev"
Requires-Dist: djangorestframework-stubs>=3.15; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Dynamic: license-file

# sinpapel-reports

Pluggable, template-driven document generation (PDF overlay + DOCX) for the
[sinpapel](https://github.com/aprendomx/sinpapel) ecosystem.

## What it does

Render per-record documents by stamping live data onto a PDF template at pixel
coordinates (ReportLab + PyPDF2) or filling a DOCX template (docxtpl). Output is
persisted as `sinpapel.InstanciaDocumento`, optionally bundled as a ZIP.

## Install

```bash
pip install sinpapel-reports
```

Add `"sinpapel_reports"` to `INSTALLED_APPS` (after `"sinpapel"`).

## Plug in your data

Declare a `reports.py` in any installed app:

```python
from sinpapel_reports.data_sources import CampoReporte, register_data_source

@register_data_source
class SolicitudDataSource:
    name = "solicitud"
    def get_field_catalog(self):
        return [CampoReporte(key="folio", label="Folio")]
    def build_context(self, target):
        return {"folio": target.id}
```

Point a `Documento.configuracion_overlay["data_source"]` at `"solicitud"` and call
`ReportEngine.generar(documento, target)`.

## REST (optional)

Install the `drf` extra and `include("sinpapel_reports.drf.urls")`.

Endpoints (relative to the mount prefix):

| Method | Path | Description |
|--------|------|-------------|
| GET | `field-catalog/?source=<name>` | Field palette for the named data source |
| GET | `documentos/<pk>/overlay-config/` | Read stored overlay config |
| PUT | `documentos/<pk>/overlay-config/` | Persist overlay config (validated) |
| POST | `documentos/<pk>/generate/` | Generate; returns `{"instancia_id","filename"}` |
| GET | `instancias/<pk>/download/` | Download generated file as attachment |

**Auth:** views require `IsAuthenticated` by default. Override via `settings.SINPAPEL_REPORTS_PERMISSION_CLASSES`.

**Extensibility:** register custom renderers with `ReportEngine.register_renderer("XLSX", my_renderer)`.

## License

GPL-3.0-or-later.
