Metadata-Version: 2.4
Name: hermes-reports
Version: 0.1.0
Summary: Hermes Reports: engine leve de relatórios baseada em templates XML.
Author: Rogério Lima, OpenAI Codex
Keywords: reports,xml,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 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:

```bash
uv sync
```

Ou:

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

Fluxo local recomendado para validação e artefatos:

```bash
make sync
make artifact
```

Após publicação no PyPI:

```bash
pip install hermes-reports
```

## Uso por import

```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.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:

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

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

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

Compatibilidade legada:

```python
from report_engine import ReportEngine
```

## Uso via CLI

CLI oficial:

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

Ou por módulo:

```bash
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:

```bash
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:

```bash
python -m report_engine ...
report-engine ...
```

## Exemplo rápido de template

```xml
<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](./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:

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

Ou:

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

## Documentação adicional

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

## Estrutura do projeto

```text
.
├── 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.
