Metadata-Version: 2.4
Name: relatorios-sivwin
Version: 0.2.1
Summary: Consultas SQL reutilizaveis para o ecossistema SivWin/Otimiza.
Keywords: sql,django,sivwin,otimiza,relatorios
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: twine; extra == "dev"

# Relatorios SivWin

Biblioteca Python para centralizar consultas SQL do ecossistema SivWin/Otimiza.

## Instalacao

```bash
pip install relatorios-sivwin
```

O nome publicado usa hifen, mas o import Python usa underscore:

```python
from relatorios_sivwin import RelatoriosSivWin
```

## Objetivo

- Concentrar consultas SQL em um unico lugar.
- Reduzir duplicacao de regras SQL entre projetos.
- Facilitar o uso das mesmas consultas em Django, scripts e outros servicos.

## Estrutura

- `relatorios_sivwin.SQLQuery`: contrato padrao para consultas parametrizadas.
- `relatorios_sivwin.RelatoriosSivWin`: hub principal de acesso aos dominios.
- `relatorios_sivwin.RelatoriosGeraisQueries`: consultas gerais, como declaracoes e ARTs.
- `relatorios_sivwin.RelatoriosServicosQueries`: consultas do dominio de servicos e inspecoes.
- `relatorios_sivwin.dbapi`: helpers opcionais para executar uma `SQLQuery` com um cursor ja aberto.

## Exemplo Rapido

```python
from relatorios_sivwin import RelatoriosSivWin

relatorios = RelatoriosSivWin()
consulta = relatorios.gerais.relatorio_art(120000, 120999)

print(consulta.sql)
print(consulta.params)
print(consulta.columns)
```

Por padrao, a representacao SQL bruta usa `otimiza` como banco:

```python
relatorios = RelatoriosSivWin(database="sivwin_homolog")
consulta = relatorios.servicos.relatorio_completo("2026-02-01", "2026-02-28")

print(consulta.to_sql_raw())
```

## Uso Com Django

```python
from django.db import connections
from relatorios_sivwin import RelatoriosSivWin, fetch_all

relatorios = RelatoriosSivWin()
consulta = relatorios.servicos.relatorio_completo("2026-02-01", "2026-02-28")

with connections["otimiza"].cursor() as cursor:
    dados = fetch_all(cursor, consulta)
```

Nesse formato:

- o Django continua responsavel pela conexao;
- o pacote so define a consulta;
- o mesmo objeto pode ser reutilizado em outros contextos.

## Uso Fora Do Django

```python
from relatorios_sivwin import RelatoriosSivWin

relatorios = RelatoriosSivWin()
consulta = relatorios.gerais.relatorio_declaracoes(123456)

cursor.execute(consulta.sql, consulta.params)
linhas = cursor.fetchall()
```

## Principios Do Pacote

- Sem acoplamento com conexao, `.env` ou credenciais.
- Sem dependencias pesadas para gerar SQL.
- Metodos de dominio retornam `SQLQuery`.
- Queries sempre parametrizadas, sem interpolacao direta de valores.
- Cada relatorio relevante tem sua propria SQL, escrita de forma explicita.
- Reaproveitamento existe apenas onde ele realmente simplifica, como constantes SQL e bloco de contato.
