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