hermes-reports 0.2.1

Hermes Reports: engine leve de relatórios baseada em templates JRXML.

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

uv sync

Ou:

pip install -e .

Uso

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:

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:

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

Compatibilidade:

from report_engine import ReportEngine

CLI

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

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:

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:

• 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:

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

Template oficial

O formato oficial do projeto agora é JRXML. Veja:

• MANUAL.md
• AGENTS.md
• ROADMAP.md
• DEPLOY.md