Metadata-Version: 2.4
Name: hermes-reports
Version: 0.2.1
Summary: Hermes Reports: engine leve de relatórios baseada em templates JRXML.
Author: Rogério Lima, OpenAI Codex
Keywords: reports,jrxml,jasper,pdf,xlsx,html,reportlab
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: reportlab>=4.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: setuptools>=68; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# Hermes Reports

Hermes Reports é uma engine leve para renderizar relatórios a partir de templates `JRXML` do Jasper Studio. A proposta do projeto é servir como uma alternativa programável ao JasperServer, mantendo uma API Python simples e saídas em `html`, `pdf`, `csv` e `xlsx`.

O namespace público oficial é `hermes_reports`. O namespace `report_engine` continua disponível como compatibilidade.

## O que o projeto suporta hoje

- templates `JRXML` com raiz `<jasperReport>`
- bands `title`, `pageHeader`, `detail`, `summary`, `columnFooter`, `pageFooter` e `lastPageFooter`
- `staticText`, `textField`, `image`, `subreport`, `jr:table`, `jr:Code128` e `jr:QRCode`
- `parameter`, `variable` e `printWhenExpression`
- expressões Jasper simples com `$F{}`, `$P{}` e `$V{}`
- exportação `html`, `pdf`, `csv`, `xlsx` e alias `xmlx`

## Limites atuais do suporte JRXML

- o projeto importa um subconjunto pragmático do JRXML, não o dialeto completo do JasperReports Server
- `jr:table` é o caminho preferido para coleções aninhadas em `dict`
- layout posicionado do Jasper é convertido para a ordem de leitura do motor interno
- o PDF continua com base em `reportlab`
- barcode e qrcode dependem de `reportlab`, inclusive no HTML

## Instalação

```bash
uv sync
```

Ou:

```bash
pip install -e .
```

## Uso

```python
from hermes_reports import ReportEngine

dados = {
    "titulo": "Relatório de Vendas",
    "periodo": "01/01/2026 a 31/01/2026",
    "itens": [
        {"produto": "Notebook", "quantidade": 10, "valor": 3500},
        {"produto": "Mouse", "quantidade": 50, "valor": 80},
    ],
}

engine = ReportEngine("hermes_reports/templates/vendas.jrxml")

html = engine.render(dados)
pdf = engine.render(dados, output="pdf")
csv_text = engine.render(dados, output="csv")
xlsx_bytes = engine.render(dados, output="xlsx")
```

Para gravar em arquivo:

```python
engine.render_to_file(dados, "relatorio.html")
engine.render_to_file(dados, "relatorio.pdf")
engine.render_to_file(dados, "relatorio.csv")
engine.render_to_file(dados, "relatorio.xlsx")
```

Parâmetros externos continuam separados dos dados:

```python
engine.render_to_file(
    dados,
    "relatorio.pdf",
    parameters={
        "empresa": "Hermes Reports Brasil",
        "responsavel_relatorio": "Operações",
    },
)
```

Compatibilidade:

```python
from report_engine import ReportEngine
```

## CLI

```bash
hermes-reports hermes_reports/templates/vendas.jrxml hermes_reports/examples/01_basico_vendas.json -o /tmp/vendas.html
```

```bash
python -m hermes_reports hermes_reports/templates/vendas.jrxml hermes_reports/examples/01_basico_vendas.json -o /tmp/vendas.pdf -f pdf
```

Com parâmetros:

```bash
python -m hermes_reports \
  hermes_reports/examples/05_subreport_parametros_variaveis.jrxml \
  hermes_reports/examples/05_subreport_parametros_variaveis.json \
  --params hermes_reports/examples/05_params.json \
  -o /tmp/exemplo05.html
```

## Exemplos

Os exemplos oficiais ficam em [hermes_reports/examples](./hermes_reports/examples):

- `01`: cabeçalho, tabela e total
- `02`: formatação de data, número e moeda
- `03`: estilos e layout
- `04`: bands de página
- `05`: subreport, parâmetros e variáveis
- `06`: expressões e `printWhenExpression`
- `07`: imagens, barcode, qrcode e cores

O helper abaixo renderiza os exemplos:

```bash
python -m hermes_reports.examples.run_examples --example all --format html
```

## Template oficial

O formato oficial do projeto agora é `JRXML`. Veja:

- [MANUAL.md](./MANUAL.md)
- [AGENTS.md](./AGENTS.md)
- [ROADMAP.md](./ROADMAP.md)
- [DEPLOY.md](./DEPLOY.md)
