Metadata-Version: 2.4
Name: sfa-automation
Version: 0.1.0
Summary: Biblioteca simples para padronizar execução, logging e retorno em JSON de rotinas de automação.
Project-URL: Homepage, https://github.com/joseromerio/sfa-automation
Project-URL: Repository, https://github.com/joseromerio/sfa-automation
Author-email: José <jose.romerio.soares@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: automacao,automation,logging,orquestrador
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# sfa-automation

Biblioteca simples para padronizar execução, logging e retorno em formato JSON
de rotinas de automação (scripts, integrações, robôs).

## Instalação

```bash
pip install sfa-automation
```

## Uso básico

```python
from sfa_automation import Automation

def minha_rotina(auto: Automation):
    auto.info("Iniciando processamento")
    auto.set_total(10)

    for i in range(10):
        try:
            # ... lógica da rotina ...
            auto.success(f"Item {i} processado com sucesso")
        except Exception as e:
            auto.error(f"Falha no item {i}: {e}")

auto = Automation("minha_rotina")
auto.run(minha_rotina)
```

A saída é sempre um JSON impresso no `stdout`, por exemplo:

```json
{
  "status": "sucesso",
  "inicio": "2026-07-14T10:00:00",
  "duracao": 1.23,
  "total": 10,
  "sucesso": 10,
  "erros": 0,
  "avisos": 0,
  "logs": ["[INFO] Iniciando processamento", "[OK] Item 0 processado com sucesso"]
}
```

Se uma exceção não tratada ocorrer dentro da função passada para `run()`,
o traceback é automaticamente capturado e incluído no JSON de saída, com
`status` igual a `"erro"`.

## Status possíveis

| Constante | Valor | Significado |
|---|---|---|
| `Automation.STATUS_EXECUTANDO` | `executando` | Rotina em andamento |
| `Automation.STATUS_SUCESSO` | `sucesso` | Nenhum erro registrado |
| `Automation.STATUS_SUCESSO_COM_ERROS` | `sucesso_com_erros` | Houve sucesso e erros |
| `Automation.STATUS_ERRO` | `erro` | Só houve erros (ou exceção não tratada) |
| `Automation.STATUS_CANCELADO` | `cancelado` | Rotina cancelada |

## API

- `Automation(nome)` — cria uma nova instância, registrando o horário de início.
- `.info(msg)` / `.warning(msg)` / `.error(msg)` / `.success(msg)` — adicionam logs categorizados (warning/error/success também incrementam contadores).
- `.log(msg)` — adiciona um log "cru", sem prefixo.
- `.set_total(n)` — define o total esperado de itens processados.
- `.resultado()` — retorna o dicionário de resultado (sem imprimir).
- `.run(func)` — executa `func(self)`, captura exceções e imprime o JSON final em `stdout`.

## Licença

MIT
