datamais-api 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. datamais_api-0.4.0/PKG-INFO +378 -0
  2. datamais_api-0.4.0/README.md +359 -0
  3. {datamais_api-0.3.0 → datamais_api-0.4.0}/pyproject.toml +1 -1
  4. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api/__init__.py +27 -3
  5. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api/cliente.py +132 -30
  6. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api/erros.py +5 -1
  7. datamais_api-0.4.0/src/datamais_api/eventos.py +45 -0
  8. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api/modelos.py +174 -8
  9. datamais_api-0.4.0/src/datamais_api.egg-info/PKG-INFO +378 -0
  10. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api.egg-info/SOURCES.txt +3 -0
  11. datamais_api-0.4.0/tests/test_acompanhar.py +349 -0
  12. {datamais_api-0.3.0 → datamais_api-0.4.0}/tests/test_cliente.py +265 -4
  13. datamais_api-0.4.0/tests/test_eventos.py +46 -0
  14. {datamais_api-0.3.0 → datamais_api-0.4.0}/tests/test_layout.py +29 -50
  15. datamais_api-0.3.0/PKG-INFO +0 -199
  16. datamais_api-0.3.0/README.md +0 -180
  17. datamais_api-0.3.0/src/datamais_api.egg-info/PKG-INFO +0 -199
  18. {datamais_api-0.3.0 → datamais_api-0.4.0}/LICENSE +0 -0
  19. {datamais_api-0.3.0 → datamais_api-0.4.0}/setup.cfg +0 -0
  20. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api/config.py +0 -0
  21. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api/py.typed +0 -0
  22. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api.egg-info/dependency_links.txt +0 -0
  23. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api.egg-info/requires.txt +0 -0
  24. {datamais_api-0.3.0 → datamais_api-0.4.0}/src/datamais_api.egg-info/top_level.txt +0 -0
  25. {datamais_api-0.3.0 → datamais_api-0.4.0}/tests/test_config.py +0 -0
  26. {datamais_api-0.3.0 → datamais_api-0.4.0}/tests/test_pandas.py +0 -0
@@ -0,0 +1,378 @@
1
+ Metadata-Version: 2.4
2
+ Name: datamais-api
3
+ Version: 0.4.0
4
+ Summary: Cliente Python da API DataMais, feito para bots de carga de dados.
5
+ Author: SECONV-RR
6
+ License-Expression: LicenseRef-Proprietary
7
+ Project-URL: Repository, https://github.com/seconv-rr/datamais-lib-python
8
+ Project-URL: Issues, https://github.com/seconv-rr/datamais-lib-python/issues
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Natural Language :: Portuguese (Brazilian)
11
+ Classifier: Programming Language :: Python :: 3.13
12
+ Classifier: Typing :: Typed
13
+ Requires-Python: >=3.13
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: httpx>=0.28.1
17
+ Requires-Dist: pandas>=3.0.1
18
+ Dynamic: license-file
19
+
20
+ # datamais-api-python
21
+
22
+ Cliente Python da API DataMais da **SECONV-RR** (Governo do Estado de
23
+ Roraima), feito para tornar triviais os bots de carga de dados ("cargas"):
24
+ autentique com uma chave de API, leia as linhas atuais de uma fonte, envie um
25
+ snapshot de substituição completo.
26
+
27
+ O código é escrito em português sem acentos, acompanhando a API e o seu wire;
28
+ apenas o nome de distribuição e de import continua `datamais_api`.
29
+
30
+ ## Instalação
31
+
32
+ ```sh
33
+ uv add datamais-api
34
+ ```
35
+
36
+ Ou direto do repositório:
37
+
38
+ ```sh
39
+ uv add git+ssh://git@github.com/seconv-rr/datamais-api-python.git
40
+ ```
41
+
42
+ ## Configuração
43
+
44
+ O cliente lê duas variáveis de ambiente; argumentos do construtor têm
45
+ precedência sobre elas:
46
+
47
+ | Variável | Propósito |
48
+ | --- | --- |
49
+ | `DATAMAIS_BASE_URL` | URL base da API (ex.: `https://api.datamais.example`) |
50
+ | `DATAMAIS_API_KEY` | Segredo da chave de API (`dmk_...`) com concessões `view`/`manage` nas fontes alvo |
51
+
52
+ Sem `DATAMAIS_BASE_URL`, a construção do cliente levanta `ErroConfigAusente`.
53
+ `DATAMAIS_API_KEY` é opcional: omita-a para clientes somente-sessão, que
54
+ passam um `token` de sessão em vez de uma chave de máquina (veja
55
+ [Sessão de usuário](#sessão-de-usuário)).
56
+
57
+ ## Início rápido: um bot de carga
58
+
59
+ ```python
60
+ from datamais_api import ClienteDatamais, Coluna, TipoColuna
61
+
62
+ colunas = [
63
+ Coluna("convenio", "Convênio", TipoColuna.TEXTO, filtravel=True),
64
+ Coluna("valor_global", "Valor Global", TipoColuna.DINHEIRO),
65
+ Coluna("assinatura", "Assinatura", TipoColuna.DATA),
66
+ ]
67
+ linhas = [
68
+ {"convenio": "923456/2026", "valor_global": 150000.0, "assinatura": "2026-07-01"},
69
+ ]
70
+
71
+ with ClienteDatamais() as cliente:
72
+ cliente.substituir_dados_fonte("geral", "programas", colunas, linhas)
73
+ dados = cliente.obter_dados_fonte("geral", "programas")
74
+ print(dados.atualizado_em, len(dados.linhas))
75
+ ```
76
+
77
+ `substituir_dados_fonte` substitui atomicamente o catálogo de colunas e as
78
+ linhas da fonte (`PUT /v1/grupos/{grupo}/fontes/{slug}/dados`); a chave de API
79
+ precisa possuir `dataset:<grupo>:<slug>:manage` (ou a equivalente em nível de
80
+ grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
81
+ `dataset:<grupo>:<slug>:view`, a menos que a fonte seja pública.
82
+
83
+ `Coluna(..., escondida=True)` mantém os valores em cada linha sem mostrar a
84
+ coluna ao usuário, o que serve para chaves técnicas que ligam fontes.
85
+
86
+ `criar_fonte` cadastra uma fonte em um grupo (`POST /v1/grupos/{grupo}/fontes`),
87
+ para que um bot de carga possa criar a fonte que está prestes a preencher:
88
+
89
+ ```python
90
+ from datamais_api import ClienteDatamais, ErroConflito
91
+
92
+ with ClienteDatamais() as cliente:
93
+ try:
94
+ cliente.criar_fonte("geral", "programas", "Programas", descricao="SICONV")
95
+ except ErroConflito:
96
+ pass
97
+ cliente.substituir_dados_fonte("geral", "programas", colunas, linhas)
98
+ ```
99
+
100
+ `acoes` tem como padrão `ACOES_FONTE_PADRAO` (`view`, `manage`); a API sempre
101
+ acrescenta `admin`. A chave de API precisa de `group:<grupo>:manage` ou do
102
+ próprio `dataset:<grupo>:<slug>:manage` da fonte, e o grupo ainda precisa
103
+ existir e ter dono — uma chave não é um usuário, então ela nunca pode criar o
104
+ grupo. Uma fonte que já existe volta como `ErroConflito`; um grupo inexistente
105
+ ou sem dono, como `ErroValidacao` (`422`).
106
+
107
+ ## Consultas no servidor
108
+
109
+ `consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
110
+ no servidor e devolve só o resultado
111
+ (`POST /v1/grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
112
+ leva um corpo, mas não altera nada. Ela pede a mesma permissão de
113
+ `obter_dados_fonte` e aceita as mesmas credenciais: chave de API, sessão ou
114
+ nenhuma, no caso de fontes públicas.
115
+
116
+ ```python
117
+ from datamais_api import (
118
+ AgregacaoConsulta,
119
+ ClienteDatamais,
120
+ Consulta,
121
+ DirecaoOrdem,
122
+ FiltroConsulta,
123
+ OperacaoAgregacaoConsulta,
124
+ OperadorFiltroConsulta,
125
+ OrdemConsulta,
126
+ )
127
+
128
+ consulta = Consulta(
129
+ filtros=[
130
+ FiltroConsulta("assinatura", OperadorFiltroConsulta.MAIOR_IGUAL, "2026-01-01"),
131
+ FiltroConsulta("situacao", OperadorFiltroConsulta.EM, ["vigente", "suspenso"]),
132
+ ],
133
+ agrupar=["municipio"],
134
+ agregacoes=[
135
+ AgregacaoConsulta(OperacaoAgregacaoConsulta.SOMA, "valor_global"),
136
+ AgregacaoConsulta(OperacaoAgregacaoConsulta.CONTAGEM),
137
+ ],
138
+ ordenar=[OrdemConsulta("soma_valor_global", DirecaoOrdem.DESC)],
139
+ limite=10,
140
+ )
141
+
142
+ with ClienteDatamais() as cliente:
143
+ resultado = cliente.consultar_fonte("geral", "programas", consulta)
144
+ print(resultado.etag, resultado.linhas)
145
+ ```
146
+
147
+ Todo campo de `Consulta` é opcional, e o corpo leva só os que você preencher.
148
+ Sem consulta, a chamada devolve as primeiras 1000 linhas da fonte.
149
+
150
+ - `colunas` escolhe as colunas devolvidas e a ordem delas. Não pode ser usada
151
+ junto com `agrupar` ou `agregacoes`.
152
+ - Os `filtros` valem todos ao mesmo tempo. O `valor` segue o formato das
153
+ linhas do `PUT /dados` (datas em `AAAA-MM-DD`, data e hora em RFC 3339), é
154
+ uma lista com `em` e fica de fora com `nulo` e `nao_nulo`.
155
+ - `granularidade` agrupa uma coluna `date` ou `datetime` que também está em
156
+ `agrupar` por período: `GranularidadeConsulta.DIA`, `SEMANA`, `MES`,
157
+ `TRIMESTRE` ou `ANO`. O valor do grupo é o início do período, em UTC. Por
158
+ exemplo, `granularidade={"assinatura": GranularidadeConsulta.MES}` soma por
159
+ mês de assinatura.
160
+ - Cada agregação vira uma coluna chamada `<op>_<coluna>`, como
161
+ `soma_valor_global`. Uma `contagem` sem coluna conta as linhas e se chama só
162
+ `contagem`.
163
+ - `filtros_agregacao` usa o mesmo `FiltroConsulta` de `filtros`, mas filtra o
164
+ resultado das agregações pelo nome delas. Assim dá para ficar só com os
165
+ grupos em que `soma_valor_global` passa de um valor.
166
+ - `ordenar` usa `asc` quando a direção não é informada.
167
+ - `limite` vai de 1 a 10000 (o servidor usa 1000 quando ele falta), e
168
+ `deslocamento` pula até 100000 linhas antes da primeira devolvida.
169
+ - Com `total=True`, o resultado traz em `total` quantas linhas a consulta tem
170
+ antes de `limite` e `deslocamento`, o que ajuda a paginar.
171
+ - `juntar` traz colunas de uma fonte de destino de uma relação já declarada.
172
+ `JuncaoConsulta.fonte` é um `DestinoRelacao`, o mesmo tipo usado em
173
+ `definir_relacoes_fonte`.
174
+ - O servidor aceita no máximo 20 filtros, 5 colunas em `agrupar`, 10
175
+ agregações, 10 filtros de agregação e 3 junções.
176
+
177
+ O resultado é o mesmo `DadosPainel` de `obter_dados_fonte`, com `colunas`,
178
+ `linhas`, `atualizado_em`, `etag`, `total` e `sincronizando`, então os dois
179
+ podem ser usados do mesmo jeito, inclusive com `para_dataframe()`. Quando uma
180
+ linha não tem valor em uma coluna, a chave fica ausente do dicionário.
181
+ `sincronizando` é `True` enquanto alguma fonte envolvida se atualiza a partir
182
+ da origem externa em segundo plano. Nesse caso o resultado ainda usa a versão
183
+ anterior, e vale ler de novo em instantes.
184
+
185
+ Para não baixar de novo um resultado que não mudou, passe o `etag` da resposta
186
+ anterior. O cliente envia `If-None-Match`, e `consultar_fonte` devolve `None`
187
+ quando o servidor responde 304:
188
+
189
+ ```python
190
+ with ClienteDatamais() as cliente:
191
+ anterior = cliente.consultar_fonte("geral", "programas", consulta)
192
+ novo = cliente.consultar_fonte("geral", "programas", consulta, etag=anterior.etag)
193
+ resultado = novo if novo is not None else anterior
194
+ ```
195
+
196
+ Um corpo inválido levanta `ErroValidacao`, e cada item de `erros` traz o campo
197
+ em `location` (por exemplo `body.filtros[0].coluna`) e o motivo em `message`.
198
+ Uma consulta que passa do tempo limite do servidor levanta
199
+ `ErroServicoIndisponivel` (503). Um servidor que não habilitou a rota responde
200
+ 404, como acontece com uma fonte desconhecida.
201
+
202
+ ## Dados que se atualizam em segundo plano
203
+
204
+ Uma fonte ligada a uma API externa se atualiza sozinha quando é lida depois de
205
+ vencido o intervalo dela. A leitura responde na hora com a versão anterior, com
206
+ `sincronizando=True`. Fontes ligadas a uma planilha do Google se atualizam
207
+ dentro da própria leitura, então nunca chegam com `sincronizando=True`.
208
+
209
+ Para receber a versão nova sem ler de novo, use os métodos `acompanhar_*`. Eles
210
+ mantêm uma conexão aberta (Server-Sent Events) e devolvem um iterador:
211
+
212
+ ```python
213
+ from datamais_api import ClienteDatamais, DadosPainel, FalhaSincronizacao
214
+
215
+ with ClienteDatamais() as cliente:
216
+ for evento in cliente.acompanhar_dados_fonte("geral", "programas"):
217
+ match evento:
218
+ case DadosPainel():
219
+ print(evento.etag, len(evento.linhas), evento.sincronizando)
220
+ case FalhaSincronizacao():
221
+ print(evento.mensagem)
222
+ ```
223
+
224
+ | Método | Rota | Credenciais |
225
+ | --- | --- | --- |
226
+ | `acompanhar_dados_fonte(grupo, slug)` | `GET /v1/grupos/{grupo}/fontes/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (fonte pública) |
227
+ | `acompanhar_dados_fonte_independente(slug)` | `GET /v1/fontes/independentes/{slug}/dados/eventos` | só sessão |
228
+ | `acompanhar_dados_painel(grupo, slug)` | `GET /v1/grupos/{grupo}/paineis/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (painel público) |
229
+
230
+ Cada rota pede a mesma permissão da leitura comum que corresponde a ela.
231
+
232
+ O primeiro item traz os dados atuais. Quando nada está se atualizando, ele é o
233
+ único. Se vier com `sincronizando=True`, chega mais um: os dados novos, com
234
+ `sincronizando=False`, ou uma `FalhaSincronizacao`. Depois de uma falha, os
235
+ dados que já chegaram são a última versão boa, e a `mensagem` é uma frase
236
+ genérica que pode ser mostrada ao usuário final.
237
+
238
+ - Nas fontes, cada item de dados é um `DadosPainel`, como o de
239
+ `obter_dados_fonte`, e o `etag` é o mesmo da leitura comum.
240
+ - No painel, cada item de dados é um `DadosFontesPainel`, como o de
241
+ `obter_dados_painel`. O segundo item sempre vem e traz os dados novos de
242
+ todas as entradas que se atualizaram. Se algumas entradas falharem, chega
243
+ depois uma `FalhaSincronizacao` com os ids delas em `fontes`.
244
+
245
+ O iterador termina quando o servidor avisa o fim do fluxo, e a conexão fecha
246
+ nesse momento. Se a conexão cair antes, ele termina sem erro e os itens já
247
+ recebidos continuam valendo. Não reconecte em seguida: cada conexão nova é uma
248
+ leitura nova e pode disparar outra atualização. Sair do `for` antes do fim
249
+ também fecha a conexão. Se você guardar o iterador numa variável e parar de
250
+ consumi-lo no meio, chame `close()` nele.
251
+
252
+ A requisição só sai na primeira volta do `for` (ou no primeiro `next()`). Uma
253
+ resposta de erro, como 403, 404, 500 ou 429 quando um chamador anônimo passa do
254
+ limite, levanta a exceção tipada de sempre antes de qualquer item. Sem sessão,
255
+ `acompanhar_dados_fonte_independente` levanta `ErroSessaoObrigatoria` já na
256
+ chamada. O servidor encerra o fluxo no máximo no tempo limite de busca dele
257
+ (30 s por padrão) depois do primeiro item, e o cliente espera até 90 s por cada
258
+ item, ou o `timeout` do cliente, se ele for maior.
259
+
260
+ `obter_dados_painel` lê de uma vez os dados de todas as entradas de fonte de um
261
+ painel (`GET /v1/grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
262
+ pelo id da entrada, `negado` lista as entradas que o chamador não pode ler e
263
+ `relacoes` traz as relações entre as entradas como `RelacaoPainel`. Essa
264
+ leitura também dispara a atualização das fontes do painel, e `sincronizando`
265
+ fica `True` quando alguma delas está se atualizando em segundo plano. Nesse
266
+ caso, `acompanhar_dados_painel` entrega a versão nova.
267
+
268
+ ## Layout de painel (autoria)
269
+
270
+ Além das cargas de fonte, o cliente lê e escreve o **layout** de um painel — a
271
+ `DefinicaoPainel` (abas, grade, widgets, fontes) guardada como JSONB:
272
+
273
+ ```python
274
+ from datamais_api import ClienteDatamais
275
+
276
+ with ClienteDatamais() as cliente:
277
+ definicao = cliente.obter_layout("geral", "convenios")
278
+ if definicao is not None:
279
+ cliente.substituir_layout("geral", "convenios", definicao)
280
+ ```
281
+
282
+ `obter_layout` aceita chave de API, sessão ou nenhuma credencial (painéis
283
+ públicos) e retorna `None` quando o painel ainda não tem layout.
284
+ `substituir_layout` aceita sessão ou uma chave de API com
285
+ `panel:<grupo>:<slug>:manage` ou `group:<grupo>:manage`. O layout gravado por
286
+ uma chave fica sem autor.
287
+
288
+ Compor uma `DefinicaoPainel` em Python é trabalho do SDK de autoria irmão, o
289
+ [`datamais-sdk`](../datamais-sdk-python), que constrói e valida a definição e
290
+ a publica através deste cliente.
291
+
292
+ ## Sessão de usuário
293
+
294
+ O login na API é feito pelo Zitadel (OIDC) no navegador, então esta lib não
295
+ faz login por senha. Quem já tem o token de sessão de um usuário passa ele no
296
+ construtor:
297
+
298
+ ```python
299
+ with ClienteDatamais(token=token_da_sessao) as cliente:
300
+ usuario = cliente.eu()
301
+ ```
302
+
303
+ A autenticação é resolvida a cada requisição: o `token` vai como
304
+ `Authorization: Bearer` e, sem ele, vai o `X-API-Chave`. As rotas que só
305
+ aceitam sessão (as de fontes independentes) levantam `ErroSessaoObrigatoria`
306
+ sem token, antes de fazer a requisição.
307
+
308
+ `eu` devolve o `Usuario` da sessão, ou `None` quando ela não vale mais.
309
+ `eu(token)` usa outro token só naquela chamada. `sair` revoga a sessão na API
310
+ e descarta o token do cliente.
311
+
312
+ ## pandas
313
+
314
+ `DadosPainel.para_dataframe()` retorna as linhas como um DataFrame ordenado
315
+ pelo catálogo de colunas. Para cargas, `substituir_dados_fonte_de_dataframe`
316
+ envia um DataFrame inteiro em uma única chamada, inferindo o catálogo de
317
+ colunas a partir dos dtypes (bool → `bool`, inteiro → `int`, float →
318
+ `number`, datetime → `datetime`, o resto → `text`), a menos que uma lista
319
+ explícita de `colunas` seja passada. NaN e NaT viram `null`, e timestamps são
320
+ serializados como ISO-8601.
321
+
322
+ ```python
323
+ import pandas as pd
324
+ from datamais_api import ClienteDatamais
325
+
326
+ quadro = pd.read_csv("convenios.csv")
327
+
328
+ with ClienteDatamais() as cliente:
329
+ cliente.substituir_dados_fonte_de_dataframe("geral", "programas", quadro)
330
+ ```
331
+
332
+ Vale a pena passar o catálogo explicitamente sempre que o painel se importa
333
+ com a renderização: a inferência não tem como adivinhar `money`, `date`,
334
+ `link`, `percent` nem quais colunas são `filtravel`.
335
+
336
+ ## Erros
337
+
338
+ Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
339
+ `detalhe` e a lista estruturada `erros` da API:
340
+
341
+ - `ErroAutenticacao` (401) — chave ausente, inválida, expirada ou revogada
342
+ - `ErroProibido` (403) — a chave não possui a permissão exigida
343
+ - `ErroNaoEncontrado` (404) — fonte desconhecida (grupo, slug)
344
+ - `ErroConflito` (409)
345
+ - `ErroValidacao` (422) — colunas/linhas malformadas
346
+ - `ErroServicoIndisponivel` (503)
347
+ - `ErroAPI` — qualquer outro status não-2xx
348
+
349
+ Todas são subclasses de `ErroAPI`, que por sua vez é subclasse de
350
+ `ErroDatamais`, ao lado de `ErroConfigAusente` e `ErroSessaoObrigatoria`.
351
+
352
+ ## Consumidores
353
+
354
+ - [`datamais-cargas`](../datamais-cargas) — os jobs de carga que alimentam as fontes.
355
+ - [`datamais-sdk`](../datamais-sdk-python) — o SDK de autoria de painéis.
356
+
357
+ ## Publicação
358
+
359
+ Todo push na `main` roda o workflow de release: o python-semantic-release
360
+ calcula a próxima versão a partir dos Conventional Commits, escreve-a em
361
+ `pyproject.toml` e em `src/datamais_api/__init__.py`, cria a tag, atualiza o
362
+ changelog, compila com uv e — somente quando uma nova versão foi cortada —
363
+ publica no PyPI via `uv publish`, usando PyPI Trusted Publishing (sem
364
+ segredos de token).
365
+
366
+ Configuração única no PyPI: adicionar um trusted publisher para o projeto
367
+ `datamais-api` apontando para o repositório `seconv-rr/datamais-api-python` e
368
+ o workflow `release.yml`.
369
+
370
+ ## Desenvolvimento
371
+
372
+ ```sh
373
+ uv sync # instala as dependências
374
+ uv run pytest # testes (offline, transporte mockado)
375
+ uv run ruff check src tests # lint
376
+ uv run ruff format src tests # formatação
377
+ uv run basedpyright src # checagem de tipos
378
+ ```