Metadata-Version: 2.4
Name: simple-python-audit
Version: 1.3.0
Summary: Ferramenta de profiling com widget flutuante, exportação CSV e servidor de gerenciamento de logs.
Author-email: Sadson Diego <sadsondiego@gmail.com>
License: MIT
Keywords: odoo,profiler,performance,pyinstrument,audit
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Framework :: Odoo
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pyinstrument>=4.6.0
Requires-Dist: typing-extensions>=4.0.0

# Simple Python Audit Tool 🚀

Ferramenta completa para medição de performance e auditoria de variáveis para Python.

## 📦 Instalação

```bash
pip install .
# Ou via GitHub
pip install git+https://github.com/sadson/simple_python_audit.git
```

## 🎯 Como Usar

```python
from simple_python_audit import profile

@profile(
    html=True,
    trace=True,
    deep=True,
    print_terminal=True,
    save_csv=True,
    output_path="/tmp/simple_python_audit_perf",
)
def meu_metodo_lento(self):
    # Seu código aqui
```

### Parâmetros do decorador

| Parâmetro        | Padrão                              | Descrição                                                                 |
|------------------|-------------------------------------|---------------------------------------------------------------------------|
| `html`           | `False`                             | Gera relatório interativo em HTML com widget flutuante                    |
| `trace`          | `False`                             | Rastreia chamadas de funções e coleta métricas por função                 |
| `deep`           | `False`                             | Aumenta granularidade do profiler (intervalo de 0,0001 s em vez de 0,001 s) |
| `print_terminal` | `False`                             | Imprime tabela de métricas formatada no terminal ao final da execução     |
| `save_csv`       | `False`                             | Salva os dados em arquivos CSV prontos para análise com pandas/IA         |
| `output_path`    | `"/tmp/simple_python_audit_perf"`   | Diretório onde os relatórios (HTML e CSV) serão gravados                  |

---

## 📊 Saída no Terminal (`print_terminal=True`)

Exibe uma tabela formatada diretamente no stdout ao término da função:

```
==============================================================
  AUDIT: meu_metodo_lento  |  1.2345s
==============================================================
  CPU Total:             0.4567s
  CPU Usage:             37.0%
  Memory Current:        12.345 MB
  Memory Peak:           15.678 MB
  Memory Avg/Call:       2.34 KB/call
  Total Calls Traced:    1234
--------------------------------------------------------------
  Top Functions by CPU Time:
  Function                        Calls     Total       Avg      Peak
  meu_metodo_lento                    1   1.2300s  1.23000s  1.23000s
  _query                             42   0.4500s  0.01071s  0.02100s
  ...
--------------------------------------------------------------
  Top Functions by Memory:
  Function                        Calls   Total KB   Avg KB  Peak KB
  _query                             42     512.30    12.20    48.50
  ...
```

---

## 💾 Exportação CSV (`save_csv=True`)

Gera dois arquivos CSV em `output_path`, ideais para carregar em um `DataFrame` do pandas, alimentar uma IA ou construir dashboards.

### `AUDIT_{func}_{timestamp}_summary.csv`

Uma linha por execução com as métricas globais da chamada. Acumulando múltiplas execuções é possível rastrear regressões de performance ao longo do tempo.

| Coluna                  | Tipo    | Descrição                                      |
|-------------------------|---------|------------------------------------------------|
| `timestamp`             | int     | Unix timestamp da execução                     |
| `func_name`             | str     | Nome da função decorada                        |
| `duration_s`            | float   | Tempo total de execução (segundos)             |
| `cpu_total_s`           | float   | Tempo de CPU consumido (segundos)              |
| `cpu_pct`               | float   | Percentual de uso de CPU                       |
| `mem_current_mb`        | float   | Memória alocada ao final (MB)                  |
| `mem_peak_mb`           | float   | Pico de memória durante a execução (MB)        |
| `mem_avg_kb_per_call`   | float   | Média de memória por chamada de função (KB)    |
| `total_calls_traced`    | int     | Total de chamadas de função rastreadas         |

### `AUDIT_{func}_{timestamp}_trace.csv`

Uma linha por função rastreada (requer `trace=True`). Permite identificar os gargalos com precisão.

| Coluna             | Tipo  | Descrição                                     |
|--------------------|-------|-----------------------------------------------|
| `timestamp`        | int   | Unix timestamp — chave para junção com summary |
| `func_name`        | str   | Nome da função decorada                       |
| `called_function`  | str   | Nome da função rastreada                      |
| `call_count`       | int   | Número de chamadas                            |
| `total_time_s`     | float | Tempo total acumulado (segundos)              |
| `avg_time_s`       | float | Tempo médio por chamada (segundos)            |
| `peak_time_s`      | float | Pico de tempo em uma única chamada (segundos) |
| `total_mem_kb`     | float | Memória total alocada (KB)                    |
| `avg_mem_kb`       | float | Memória média por chamada (KB)                |
| `peak_mem_kb`      | float | Pico de memória em uma única chamada (KB)     |

### Exemplo de análise com pandas

```python
import pandas as pd
import glob

# Carregar todos os resumos de execuções
summary = pd.concat([pd.read_csv(f) for f in glob.glob("/tmp/simple_python_audit_perf/*_summary.csv")])
summary["timestamp"] = pd.to_datetime(summary["timestamp"], unit="s")
summary.sort_values("timestamp").plot(x="timestamp", y="duration_s", title="Evolução do tempo de execução")

# Carregar trace de uma execução específica
trace = pd.read_csv("/tmp/simple_python_audit_perf/AUDIT_meu_metodo_lento_1234567890_trace.csv")
trace.sort_values("total_time_s", ascending=False).head(10)
```

---

## 🌐 Relatório HTML (`html=True`)

Gera um arquivo `AUDIT_{func}_{timestamp}.html` com um widget flutuante interativo contendo:

- **Painel de rastreamento (🚀):** tabela de chamadas de função com busca em tempo real
- **Painel de métricas (📊):** cards de CPU e memória, tabelas de CPU e memória por função

---

## 🛠️ Servidor de Auditoria

Interface web para visualizar e gerenciar os arquivos de relatório gerados.

```bash
# Via linha de comando
simple-python-audit-server --port 8080 --dir /tmp/simple_python_audit_perf

# Via Python
from simple_python_audit import start_server
start_server(port=8080, directory="/tmp/simple_python_audit_perf")
```

---

## 🔗 Integração com Odoo

Ao instalar em um ambiente com Odoo, o decorador `profile` é injetado automaticamente em `odoo.api`:

```python
from odoo import api

@api.profile(html=True, trace=True, print_terminal=True, save_csv=True)
def action_processar(self):
    ...
```
