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

These details have not been verified by PyPI

Project description

Hermes Reports

Hermes Reports é uma engine leve de geração de relatórios baseada em templates XML, desenhada para Python puro e com reportlab como base para PDF. O projeto expõe uma API simples para uso por import e também uma CLI oficial.

O namespace público recomendado agora é hermes_reports. O namespace report_engine continua disponível por compatibilidade.

Recursos

Parser XML com validação estrutural e semântica.
Renderização a partir de dict ou list[dict].
Exportação para html, pdf, csv e xlsx.
Alias xmlx para compatibilidade com integrações legadas.
Suporte a title, subtitle, text, image, barcode, qrcode, table, detail, subreport e total.
Formatação nativa para currency, date e number.
Agregações sum e count, com estrutura pronta para avg.
expression, visible_if, group_by, parameters e variables.
Estilos reutilizáveis no XML.
Fontes, alinhamento, transformação de texto, cores, fundos e bordas configuráveis por XML.
Largura de coluna em auto ou mm.
Margens em milímetros.
Bands de página em PDF com page_header, page_footer e last_page_footer.
CSV e XLSX exportam apenas dados tabulares.
XLSX com tipos nativos para número, moeda e data.

Instalação

Para desenvolvimento local:

uv sync

Ou:

pip install -e .

Fluxo local recomendado para validação e artefatos:

make sync
make artifact

Após publicação no PyPI:

pip install hermes-reports

Uso por import

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.xml")

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 direto 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")

Também é possível injetar parâmetros externos:

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

Compatibilidade legada:

from report_engine import ReportEngine

Uso via CLI

CLI oficial:

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

Ou por módulo:

python -m hermes_reports hermes_reports/templates/vendas.xml 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.xml \
  hermes_reports/examples/05_subreport_parametros_variaveis.json \
  --params hermes_reports/examples/05_params.json \
  -o /tmp/exemplo05.pdf

Compatibilidade legada:

python -m report_engine ...
report-engine ...

Exemplo rápido de template

<report
    name="vendas"
    margin_top_mm="16"
    margin_right_mm="15"
    margin_bottom_mm="16"
    margin_left_mm="15"
>
    <styles>
        <style name="title-main" font_family="Georgia" font_size_pt="20" text_transform="uppercase"/>
        <style
            name="col-money"
            width="30mm"
            align="right"
            header_align="center"
            header_font_family="Helvetica"
            header_font_size_pt="9"
            header_text_transform="uppercase"
        />
    </styles>

    <header>
        <image src="assets/logo_vendas.png" width_mm="34"/>
        <title field="titulo" style="title-main"/>
        <subtitle field="periodo"/>
    </header>

    <body>
        <table data="itens">
            <columns>
                <column field="produto" label="Produto" width="auto"/>
                <column field="valor" label="Valor" format="currency" style="col-money"/>
            </columns>
        </table>
    </body>

    <footer>
        <total data="itens" field="valor" operation="sum" label="Total" format="currency"/>
    </footer>
</report>

Funcionalidades do XML

Seções suportadas:

<styles>
<parameters>
<variables>
<header>
<page_header>
<body>
<footer>
<page_footer>
<last_page_footer>

Elementos suportados:

<title>
<subtitle>
<text>
<image>
<barcode>
<qrcode>
<table>
<detail>
<subreport>
<column>
<total>
<parameter>
<variable>

Principais atributos:

field
expression
value
format
visible_if
data
group_by
style
header_style
align
header_align
width
width_mm
height_mm
font_family
font_size_pt
text_transform
header_font_family
header_font_size_pt
header_text_transform
color
background_color
border_color
header_color
header_background_color
header_border_color
page_break_before
keep_together

Regras relevantes:

width="auto" é o padrão.
width="Nmm" fixa largura e força quebra de conteúdo em HTML e PDF.
alinhamento padrão de células é left.
cabeçalhos podem usar alinhamento e fonte próprios.
cores usam #RRGGBB.
imagens podem ser estáticas com src ou dinâmicas com field e expression.
barcode e qrcode são renderizados em HTML e PDF.
csv e xlsx exportam apenas tabelas.

Exemplos numerados

Os exemplos numerados ficam em hermes_reports/examples e cobrem os blocos principais da biblioteca:

01: relatório básico com cabeçalho, tabela e total.
02: formatação de data, número, moeda e agregações.
03: estilos, fontes, alinhamento, larguras e cores.
04: bands de página, paginação e detail.
05: subreport, parâmetros e variáveis.
06: expression, visible_if e group_by.
07: imagem dinâmica, barcode, qrcode e cores hexadecimais.

Para renderizar todos:

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

Ou:

hermes-reports-examples --example 07 --format pdf

Documentação adicional

MANUAL.md: guia de criação de templates XML e payloads JSON.
DEPLOY.md: fluxo de build e publicação no PyPI.
ROADMAP.md: evolução técnica planejada.
AGENTS.md: especificação operacional do projeto.
Makefile: atalhos para validação e geração de artefatos.

Estrutura do projeto

.
├── AGENTS.md
├── DEPLOY.md
├── MANUAL.md
├── README.md
├── ROADMAP.md
├── hermes_reports/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   ├── engine.py
│   ├── parser.py
│   ├── examples/
│   └── templates/
├── report_engine/
│   ├── __init__.py
│   ├── __main__.py
│   ├── engine.py
│   ├── parser.py
│   ├── renderers/
│   └── templates/
└── pyproject.toml

hermes_reports é o namespace público recomendado. report_engine continua existindo como camada de compatibilidade.

Status do roadmap

Fase 1: concluída.
Fase 2: em andamento.
Fase 3: pendente.
Fase 4: concluída.
Fase 5: concluída.
Fase 6: concluída.
Fase 7: concluída.

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.2.1

Mar 29, 2026

This version

0.1.0

Mar 28, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hermes_reports-0.1.0.tar.gz (58.7 kB view details)

Uploaded Mar 28, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

hermes_reports-0.1.0-py3-none-any.whl (71.6 kB view details)

Uploaded Mar 28, 2026 Python 3

File details

Details for the file hermes_reports-0.1.0.tar.gz.

File metadata

Download URL: hermes_reports-0.1.0.tar.gz
Upload date: Mar 28, 2026
Size: 58.7 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.2

File hashes

Hashes for hermes_reports-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`19f4f8a4c2904b0b8b094c9e6a95e51011648dc595136d797653227361ce971f`
MD5	`ee6086539b0a468be50b0e945b1995e7`
BLAKE2b-256	`884c05bc6005714220e2f8f78ed5ec097f9d2ce1df39256b744802219174cadb`

See more details on using hashes here.

File details

Details for the file hermes_reports-0.1.0-py3-none-any.whl.

File metadata

Download URL: hermes_reports-0.1.0-py3-none-any.whl
Upload date: Mar 28, 2026
Size: 71.6 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.2

File hashes

Hashes for hermes_reports-0.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`5ce80f2af093fa4a31287432593fce9467c4b4e059382e91b09c66b32a2f8a6b`
MD5	`b42b39ae2022a541a7ee589e4ec9fbba`
BLAKE2b-256	`c5df42b5bd595122286a734e2552c620a895e52d79ba5dba36e57dcfa046853f`

See more details on using hashes here.

hermes-reports 0.1.0

Navigation

Verified details

Maintainers

Unverified details

Meta

Classifiers

Project description

Hermes Reports

Recursos

Instalação

Uso por import

Uso via CLI

Exemplo rápido de template

Funcionalidades do XML

Exemplos numerados

Documentação adicional

Estrutura do projeto

Status do roadmap

Project details

Verified details

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes