relatorios-sivwin 0.2.2

Consultas SQL reutilizaveis para o ecossistema SivWin/Otimiza.

Relatorios SivWin

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

Instalacao

pip install relatorios-sivwin

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

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

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:

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

print(consulta.to_sql_raw())

Uso Com Django

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

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.

Convencao De Aliases

A partir da versao 0.2.2, os aliases seguem o padrao <entidade><eventoOuAtributo><tipo>, em camelCase.

Exemplos:

• osNumero
• inspecaoConclusaoDataHora
• documentoVencimentoData
• veiculoPlaca
• proprietarioCpfCnpj

Campos de data/hora preservam o valor temporal original do banco quando a coluna de origem for DataHora. A formatacao para exibicao deve ser feita pelo consumidor.