datamais-api 0.4.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.4.0/src/datamais_api.egg-info → datamais_api-0.5.0}/PKG-INFO +31 -12
- {datamais_api-0.4.0 → datamais_api-0.5.0}/README.md +30 -11
- {datamais_api-0.4.0 → datamais_api-0.5.0}/pyproject.toml +1 -1
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/__init__.py +5 -1
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/cliente.py +39 -18
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/erros.py +23 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0/src/datamais_api.egg-info}/PKG-INFO +31 -12
- {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_acompanhar.py +25 -5
- {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_cliente.py +248 -8
- {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_layout.py +2 -2
- {datamais_api-0.4.0 → datamais_api-0.5.0}/LICENSE +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/setup.cfg +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/config.py +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/eventos.py +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/modelos.py +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/py.typed +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/SOURCES.txt +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/dependency_links.txt +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/requires.txt +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/top_level.txt +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_config.py +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_eventos.py +0 -0
- {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_pandas.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: datamais-api
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Cliente Python da API DataMais, feito para bots de carga de dados.
|
|
5
5
|
Author: SECONV-RR
|
|
6
6
|
License-Expression: LicenseRef-Proprietary
|
|
@@ -46,10 +46,13 @@ precedência sobre elas:
|
|
|
46
46
|
|
|
47
47
|
| Variável | Propósito |
|
|
48
48
|
| --- | --- |
|
|
49
|
-
| `DATAMAIS_BASE_URL` | URL base da API (ex.: `https://
|
|
49
|
+
| `DATAMAIS_BASE_URL` | URL base da API, com o prefixo do proxy reverso (ex.: `https://datamais.example/api/v1`) |
|
|
50
50
|
| `DATAMAIS_API_KEY` | Segredo da chave de API (`dmk_...`) com concessões `view`/`manage` nas fontes alvo |
|
|
51
51
|
|
|
52
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`.
|
|
53
56
|
`DATAMAIS_API_KEY` é opcional: omita-a para clientes somente-sessão, que
|
|
54
57
|
passam um `token` de sessão em vez de uma chave de máquina (veja
|
|
55
58
|
[Sessão de usuário](#sessão-de-usuário)).
|
|
@@ -75,7 +78,7 @@ with ClienteDatamais() as cliente:
|
|
|
75
78
|
```
|
|
76
79
|
|
|
77
80
|
`substituir_dados_fonte` substitui atomicamente o catálogo de colunas e as
|
|
78
|
-
linhas da fonte (`PUT /
|
|
81
|
+
linhas da fonte (`PUT /grupos/{grupo}/fontes/{slug}/dados`); a chave de API
|
|
79
82
|
precisa possuir `dataset:<grupo>:<slug>:manage` (ou a equivalente em nível de
|
|
80
83
|
grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
|
|
81
84
|
`dataset:<grupo>:<slug>:view`, a menos que a fonte seja pública.
|
|
@@ -83,7 +86,7 @@ grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
|
|
|
83
86
|
`Coluna(..., escondida=True)` mantém os valores em cada linha sem mostrar a
|
|
84
87
|
coluna ao usuário, o que serve para chaves técnicas que ligam fontes.
|
|
85
88
|
|
|
86
|
-
`criar_fonte` cadastra uma fonte em um grupo (`POST /
|
|
89
|
+
`criar_fonte` cadastra uma fonte em um grupo (`POST /grupos/{grupo}/fontes`),
|
|
87
90
|
para que um bot de carga possa criar a fonte que está prestes a preencher:
|
|
88
91
|
|
|
89
92
|
```python
|
|
@@ -108,7 +111,7 @@ ou sem dono, como `ErroValidacao` (`422`).
|
|
|
108
111
|
|
|
109
112
|
`consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
|
|
110
113
|
no servidor e devolve só o resultado
|
|
111
|
-
(`POST /
|
|
114
|
+
(`POST /grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
|
|
112
115
|
leva um corpo, mas não altera nada. Ela pede a mesma permissão de
|
|
113
116
|
`obter_dados_fonte` e aceita as mesmas credenciais: chave de API, sessão ou
|
|
114
117
|
nenhuma, no caso de fontes públicas.
|
|
@@ -223,9 +226,9 @@ with ClienteDatamais() as cliente:
|
|
|
223
226
|
|
|
224
227
|
| Método | Rota | Credenciais |
|
|
225
228
|
| --- | --- | --- |
|
|
226
|
-
| `acompanhar_dados_fonte(grupo, slug)` | `GET /
|
|
227
|
-
| `acompanhar_dados_fonte_independente(slug)` | `GET /
|
|
228
|
-
| `acompanhar_dados_painel(grupo, slug)` | `GET /
|
|
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) |
|
|
229
232
|
|
|
230
233
|
Cada rota pede a mesma permissão da leitura comum que corresponde a ela.
|
|
231
234
|
|
|
@@ -258,7 +261,7 @@ chamada. O servidor encerra o fluxo no máximo no tempo limite de busca dele
|
|
|
258
261
|
item, ou o `timeout` do cliente, se ele for maior.
|
|
259
262
|
|
|
260
263
|
`obter_dados_painel` lê de uma vez os dados de todas as entradas de fonte de um
|
|
261
|
-
painel (`GET /
|
|
264
|
+
painel (`GET /grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
|
|
262
265
|
pelo id da entrada, `negado` lista as entradas que o chamador não pode ler e
|
|
263
266
|
`relacoes` traz as relações entre as entradas como `RelacaoPainel`. Essa
|
|
264
267
|
leitura também dispara a atualização das fontes do painel, e `sincronizando`
|
|
@@ -335,9 +338,10 @@ com a renderização: a inferência não tem como adivinhar `money`, `date`,
|
|
|
335
338
|
|
|
336
339
|
## Erros
|
|
337
340
|
|
|
338
|
-
Toda resposta não-2xx levanta uma exceção tipada carregando
|
|
339
|
-
`detalhe` e a lista estruturada `erros` da API:
|
|
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:
|
|
340
343
|
|
|
344
|
+
- `ErroRedirecionamento` (3xx, menos 304)
|
|
341
345
|
- `ErroAutenticacao` (401) — chave ausente, inválida, expirada ou revogada
|
|
342
346
|
- `ErroProibido` (403) — a chave não possui a permissão exigida
|
|
343
347
|
- `ErroNaoEncontrado` (404) — fonte desconhecida (grupo, slug)
|
|
@@ -347,7 +351,22 @@ Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
|
|
|
347
351
|
- `ErroAPI` — qualquer outro status não-2xx
|
|
348
352
|
|
|
349
353
|
Todas são subclasses de `ErroAPI`, que por sua vez é subclasse de
|
|
350
|
-
`ErroDatamais`, ao lado de `ErroConfigAusente` e
|
|
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`.
|
|
351
370
|
|
|
352
371
|
## Consumidores
|
|
353
372
|
|
|
@@ -27,10 +27,13 @@ precedência sobre elas:
|
|
|
27
27
|
|
|
28
28
|
| Variável | Propósito |
|
|
29
29
|
| --- | --- |
|
|
30
|
-
| `DATAMAIS_BASE_URL` | URL base da API (ex.: `https://
|
|
30
|
+
| `DATAMAIS_BASE_URL` | URL base da API, com o prefixo do proxy reverso (ex.: `https://datamais.example/api/v1`) |
|
|
31
31
|
| `DATAMAIS_API_KEY` | Segredo da chave de API (`dmk_...`) com concessões `view`/`manage` nas fontes alvo |
|
|
32
32
|
|
|
33
33
|
Sem `DATAMAIS_BASE_URL`, a construção do cliente levanta `ErroConfigAusente`.
|
|
34
|
+
O cliente não acrescenta prefixo nenhum e coloca cada rota logo depois dessa
|
|
35
|
+
URL. Por isso ela já precisa trazer o caminho que o proxy reverso publica, como
|
|
36
|
+
`/api/v1`.
|
|
34
37
|
`DATAMAIS_API_KEY` é opcional: omita-a para clientes somente-sessão, que
|
|
35
38
|
passam um `token` de sessão em vez de uma chave de máquina (veja
|
|
36
39
|
[Sessão de usuário](#sessão-de-usuário)).
|
|
@@ -56,7 +59,7 @@ with ClienteDatamais() as cliente:
|
|
|
56
59
|
```
|
|
57
60
|
|
|
58
61
|
`substituir_dados_fonte` substitui atomicamente o catálogo de colunas e as
|
|
59
|
-
linhas da fonte (`PUT /
|
|
62
|
+
linhas da fonte (`PUT /grupos/{grupo}/fontes/{slug}/dados`); a chave de API
|
|
60
63
|
precisa possuir `dataset:<grupo>:<slug>:manage` (ou a equivalente em nível de
|
|
61
64
|
grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
|
|
62
65
|
`dataset:<grupo>:<slug>:view`, a menos que a fonte seja pública.
|
|
@@ -64,7 +67,7 @@ grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
|
|
|
64
67
|
`Coluna(..., escondida=True)` mantém os valores em cada linha sem mostrar a
|
|
65
68
|
coluna ao usuário, o que serve para chaves técnicas que ligam fontes.
|
|
66
69
|
|
|
67
|
-
`criar_fonte` cadastra uma fonte em um grupo (`POST /
|
|
70
|
+
`criar_fonte` cadastra uma fonte em um grupo (`POST /grupos/{grupo}/fontes`),
|
|
68
71
|
para que um bot de carga possa criar a fonte que está prestes a preencher:
|
|
69
72
|
|
|
70
73
|
```python
|
|
@@ -89,7 +92,7 @@ ou sem dono, como `ErroValidacao` (`422`).
|
|
|
89
92
|
|
|
90
93
|
`consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
|
|
91
94
|
no servidor e devolve só o resultado
|
|
92
|
-
(`POST /
|
|
95
|
+
(`POST /grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
|
|
93
96
|
leva um corpo, mas não altera nada. Ela pede a mesma permissão de
|
|
94
97
|
`obter_dados_fonte` e aceita as mesmas credenciais: chave de API, sessão ou
|
|
95
98
|
nenhuma, no caso de fontes públicas.
|
|
@@ -204,9 +207,9 @@ with ClienteDatamais() as cliente:
|
|
|
204
207
|
|
|
205
208
|
| Método | Rota | Credenciais |
|
|
206
209
|
| --- | --- | --- |
|
|
207
|
-
| `acompanhar_dados_fonte(grupo, slug)` | `GET /
|
|
208
|
-
| `acompanhar_dados_fonte_independente(slug)` | `GET /
|
|
209
|
-
| `acompanhar_dados_painel(grupo, slug)` | `GET /
|
|
210
|
+
| `acompanhar_dados_fonte(grupo, slug)` | `GET /grupos/{grupo}/fontes/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (fonte pública) |
|
|
211
|
+
| `acompanhar_dados_fonte_independente(slug)` | `GET /fontes/independentes/{slug}/dados/eventos` | só sessão |
|
|
212
|
+
| `acompanhar_dados_painel(grupo, slug)` | `GET /grupos/{grupo}/paineis/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (painel público) |
|
|
210
213
|
|
|
211
214
|
Cada rota pede a mesma permissão da leitura comum que corresponde a ela.
|
|
212
215
|
|
|
@@ -239,7 +242,7 @@ chamada. O servidor encerra o fluxo no máximo no tempo limite de busca dele
|
|
|
239
242
|
item, ou o `timeout` do cliente, se ele for maior.
|
|
240
243
|
|
|
241
244
|
`obter_dados_painel` lê de uma vez os dados de todas as entradas de fonte de um
|
|
242
|
-
painel (`GET /
|
|
245
|
+
painel (`GET /grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
|
|
243
246
|
pelo id da entrada, `negado` lista as entradas que o chamador não pode ler e
|
|
244
247
|
`relacoes` traz as relações entre as entradas como `RelacaoPainel`. Essa
|
|
245
248
|
leitura também dispara a atualização das fontes do painel, e `sincronizando`
|
|
@@ -316,9 +319,10 @@ com a renderização: a inferência não tem como adivinhar `money`, `date`,
|
|
|
316
319
|
|
|
317
320
|
## Erros
|
|
318
321
|
|
|
319
|
-
Toda resposta não-2xx levanta uma exceção tipada carregando
|
|
320
|
-
`detalhe` e a lista estruturada `erros` da API:
|
|
322
|
+
Toda resposta não-2xx, menos o 304, levanta uma exceção tipada carregando
|
|
323
|
+
`status`, `detalhe` e a lista estruturada `erros` da API:
|
|
321
324
|
|
|
325
|
+
- `ErroRedirecionamento` (3xx, menos 304)
|
|
322
326
|
- `ErroAutenticacao` (401) — chave ausente, inválida, expirada ou revogada
|
|
323
327
|
- `ErroProibido` (403) — a chave não possui a permissão exigida
|
|
324
328
|
- `ErroNaoEncontrado` (404) — fonte desconhecida (grupo, slug)
|
|
@@ -328,7 +332,22 @@ Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
|
|
|
328
332
|
- `ErroAPI` — qualquer outro status não-2xx
|
|
329
333
|
|
|
330
334
|
Todas são subclasses de `ErroAPI`, que por sua vez é subclasse de
|
|
331
|
-
`ErroDatamais`, ao lado de `ErroConfigAusente` e
|
|
335
|
+
`ErroDatamais`, ao lado de `ErroConfigAusente`, `ErroSessaoObrigatoria` e
|
|
336
|
+
`ErroSegmentoInvalido`.
|
|
337
|
+
|
|
338
|
+
O cliente não segue redirecionamentos, porque seguir um 3xx reenviaria a chave
|
|
339
|
+
de API ou o token de sessão para o endereço do `Location`, que pode ser outro
|
|
340
|
+
host. Qualquer 3xx, menos o 304, levanta `ErroRedirecionamento`, com o `status`
|
|
341
|
+
e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
|
|
342
|
+
cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
|
|
343
|
+
endereço final, por exemplo trocando `http://` por `https://`.
|
|
344
|
+
|
|
345
|
+
Cada `grupo` e `slug` entra na rota como um único segmento codificado, então
|
|
346
|
+
`/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um `grupo` ou `slug`
|
|
347
|
+
vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
|
|
348
|
+
requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
|
|
349
|
+
nele, então a chamada poderia ir para outra rota com as suas credenciais. O
|
|
350
|
+
valor recusado fica em `segmento`.
|
|
332
351
|
|
|
333
352
|
## Consumidores
|
|
334
353
|
|
|
@@ -8,6 +8,8 @@ from datamais_api.erros import (
|
|
|
8
8
|
ErroDatamais,
|
|
9
9
|
ErroNaoEncontrado,
|
|
10
10
|
ErroProibido,
|
|
11
|
+
ErroRedirecionamento,
|
|
12
|
+
ErroSegmentoInvalido,
|
|
11
13
|
ErroServicoIndisponivel,
|
|
12
14
|
ErroSessaoObrigatoria,
|
|
13
15
|
ErroValidacao,
|
|
@@ -50,7 +52,7 @@ from datamais_api.modelos import (
|
|
|
50
52
|
linhas_de_dataframe,
|
|
51
53
|
)
|
|
52
54
|
|
|
53
|
-
__version__ = "0.
|
|
55
|
+
__version__ = "0.5.0"
|
|
54
56
|
|
|
55
57
|
__all__ = [
|
|
56
58
|
"ACOES_FONTE_PADRAO",
|
|
@@ -90,6 +92,8 @@ __all__ = [
|
|
|
90
92
|
"DefinicaoPainel",
|
|
91
93
|
"FontePainel",
|
|
92
94
|
"Linha",
|
|
95
|
+
"ErroRedirecionamento",
|
|
96
|
+
"ErroSegmentoInvalido",
|
|
93
97
|
"ErroSessaoObrigatoria",
|
|
94
98
|
"Configuracoes",
|
|
95
99
|
"Aba",
|
|
@@ -3,6 +3,7 @@ from collections.abc import Callable, Iterator
|
|
|
3
3
|
from datetime import datetime
|
|
4
4
|
from types import TracebackType
|
|
5
5
|
from typing import Any, overload
|
|
6
|
+
from urllib.parse import quote
|
|
6
7
|
|
|
7
8
|
import httpx
|
|
8
9
|
import pandas as pd
|
|
@@ -12,6 +13,7 @@ from datamais_api.erros import (
|
|
|
12
13
|
ErroAutenticacao,
|
|
13
14
|
ErroDatamais,
|
|
14
15
|
ErroNaoEncontrado,
|
|
16
|
+
ErroSegmentoInvalido,
|
|
15
17
|
ErroSessaoObrigatoria,
|
|
16
18
|
de_resposta,
|
|
17
19
|
)
|
|
@@ -53,6 +55,7 @@ class ClienteDatamais:
|
|
|
53
55
|
base_url=config.url_base,
|
|
54
56
|
timeout=timeout,
|
|
55
57
|
transport=transport,
|
|
58
|
+
follow_redirects=False,
|
|
56
59
|
)
|
|
57
60
|
|
|
58
61
|
@property
|
|
@@ -60,13 +63,13 @@ class ClienteDatamais:
|
|
|
60
63
|
return self._token
|
|
61
64
|
|
|
62
65
|
def obter_dados_fonte(self, grupo: str, slug: str) -> DadosPainel:
|
|
63
|
-
return _dados_de(self._requisitar("GET",
|
|
66
|
+
return _dados_de(self._requisitar("GET", _rota("/grupos/{}/fontes/{}/dados", grupo, slug)))
|
|
64
67
|
|
|
65
68
|
def acompanhar_dados_fonte(
|
|
66
69
|
self, grupo: str, slug: str
|
|
67
70
|
) -> Iterator[DadosPainel | FalhaSincronizacao]:
|
|
68
71
|
return self._acompanhar(
|
|
69
|
-
|
|
72
|
+
_rota("/grupos/{}/fontes/{}/dados/eventos", grupo, slug), _dados_de_evento
|
|
70
73
|
)
|
|
71
74
|
|
|
72
75
|
def acompanhar_dados_fonte_independente(
|
|
@@ -74,17 +77,19 @@ class ClienteDatamais:
|
|
|
74
77
|
) -> Iterator[DadosPainel | FalhaSincronizacao]:
|
|
75
78
|
if not self._token:
|
|
76
79
|
raise ErroSessaoObrigatoria("Acompanhar os dados de uma fonte independente")
|
|
77
|
-
return self._acompanhar(
|
|
80
|
+
return self._acompanhar(
|
|
81
|
+
_rota("/fontes/independentes/{}/dados/eventos", slug), _dados_de_evento
|
|
82
|
+
)
|
|
78
83
|
|
|
79
84
|
def obter_dados_painel(self, grupo: str, slug: str) -> DadosFontesPainel:
|
|
80
|
-
resposta = self._requisitar("GET",
|
|
85
|
+
resposta = self._requisitar("GET", _rota("/grupos/{}/paineis/{}/dados", grupo, slug))
|
|
81
86
|
return _dados_painel_de_corpo(resposta.json(), _sincronizando(resposta))
|
|
82
87
|
|
|
83
88
|
def acompanhar_dados_painel(
|
|
84
89
|
self, grupo: str, slug: str
|
|
85
90
|
) -> Iterator[DadosFontesPainel | FalhaSincronizacao]:
|
|
86
91
|
return self._acompanhar(
|
|
87
|
-
|
|
92
|
+
_rota("/grupos/{}/paineis/{}/dados/eventos", grupo, slug), _dados_painel_de_evento
|
|
88
93
|
)
|
|
89
94
|
|
|
90
95
|
@overload
|
|
@@ -103,7 +108,7 @@ class ClienteDatamais:
|
|
|
103
108
|
payload = consulta.para_payload() if consulta is not None else {}
|
|
104
109
|
resposta = self._requisitar(
|
|
105
110
|
"POST",
|
|
106
|
-
|
|
111
|
+
_rota("/grupos/{}/fontes/{}/consulta", grupo, slug),
|
|
107
112
|
json=payload,
|
|
108
113
|
headers={"If-None-Match": etag} if etag else None,
|
|
109
114
|
)
|
|
@@ -118,7 +123,7 @@ class ClienteDatamais:
|
|
|
118
123
|
"colunas": [coluna.para_payload() for coluna in colunas],
|
|
119
124
|
"linhas": linhas,
|
|
120
125
|
}
|
|
121
|
-
self._requisitar("PUT",
|
|
126
|
+
self._requisitar("PUT", _rota("/grupos/{}/fontes/{}/dados", grupo, slug), json=payload)
|
|
122
127
|
|
|
123
128
|
def substituir_dados_fonte_de_dataframe(
|
|
124
129
|
self,
|
|
@@ -149,28 +154,30 @@ class ClienteDatamais:
|
|
|
149
154
|
}
|
|
150
155
|
if descricao:
|
|
151
156
|
payload["descricao"] = descricao
|
|
152
|
-
body = self._requisitar("POST",
|
|
157
|
+
body = self._requisitar("POST", _rota("/grupos/{}/fontes", grupo), json=payload).json()
|
|
153
158
|
return Fonte.de_payload(body["fonte"])
|
|
154
159
|
|
|
155
160
|
def obter_relacoes_fonte(self, grupo: str, slug: str) -> list[RelacaoFonte]:
|
|
156
|
-
return self._obter_relacoes(
|
|
161
|
+
return self._obter_relacoes(_rota("/grupos/{}/fontes/{}/relacoes", grupo, slug))
|
|
157
162
|
|
|
158
163
|
def definir_relacoes_fonte(
|
|
159
164
|
self, grupo: str, slug: str, relacoes: list[RelacaoFonte]
|
|
160
165
|
) -> list[RelacaoFonte]:
|
|
161
|
-
return self._definir_relacoes(
|
|
166
|
+
return self._definir_relacoes(
|
|
167
|
+
_rota("/grupos/{}/fontes/{}/relacoes", grupo, slug), relacoes
|
|
168
|
+
)
|
|
162
169
|
|
|
163
170
|
def obter_relacoes_fonte_independente(self, slug: str) -> list[RelacaoFonte]:
|
|
164
171
|
if not self._token:
|
|
165
172
|
raise ErroSessaoObrigatoria("Obter as relações de uma fonte independente")
|
|
166
|
-
return self._obter_relacoes(
|
|
173
|
+
return self._obter_relacoes(_rota("/fontes/independentes/{}/relacoes", slug))
|
|
167
174
|
|
|
168
175
|
def definir_relacoes_fonte_independente(
|
|
169
176
|
self, slug: str, relacoes: list[RelacaoFonte]
|
|
170
177
|
) -> list[RelacaoFonte]:
|
|
171
178
|
if not self._token:
|
|
172
179
|
raise ErroSessaoObrigatoria("Definir as relações de uma fonte independente")
|
|
173
|
-
return self._definir_relacoes(
|
|
180
|
+
return self._definir_relacoes(_rota("/fontes/independentes/{}/relacoes", slug), relacoes)
|
|
174
181
|
|
|
175
182
|
def _obter_relacoes(self, caminho: str) -> list[RelacaoFonte]:
|
|
176
183
|
body = self._requisitar("GET", caminho).json()
|
|
@@ -182,8 +189,9 @@ class ClienteDatamais:
|
|
|
182
189
|
return _relacoes_de(body)
|
|
183
190
|
|
|
184
191
|
def obter_layout(self, grupo: str, slug: str) -> DefinicaoPainel | None:
|
|
192
|
+
caminho = _rota("/grupos/{}/paineis/{}/layout", grupo, slug)
|
|
185
193
|
try:
|
|
186
|
-
body = self._requisitar("GET",
|
|
194
|
+
body = self._requisitar("GET", caminho).json()
|
|
187
195
|
except ErroNaoEncontrado:
|
|
188
196
|
return None
|
|
189
197
|
return DefinicaoPainel.de_payload(body)
|
|
@@ -191,20 +199,20 @@ class ClienteDatamais:
|
|
|
191
199
|
def substituir_layout(self, grupo: str, slug: str, definicao: DefinicaoPainel) -> None:
|
|
192
200
|
self._requisitar(
|
|
193
201
|
"PUT",
|
|
194
|
-
|
|
202
|
+
_rota("/grupos/{}/paineis/{}/layout", grupo, slug),
|
|
195
203
|
json=definicao.para_payload(),
|
|
196
204
|
)
|
|
197
205
|
|
|
198
206
|
def eu(self, token: str | None = None) -> Usuario | None:
|
|
199
207
|
try:
|
|
200
|
-
body = self._requisitar("GET", "/
|
|
208
|
+
body = self._requisitar("GET", "/auth/eu", token=token).json()
|
|
201
209
|
except ErroAutenticacao:
|
|
202
210
|
return None
|
|
203
211
|
return Usuario.de_payload(body)
|
|
204
212
|
|
|
205
213
|
def sair(self) -> None:
|
|
206
214
|
try:
|
|
207
|
-
self._requisitar("POST", "/
|
|
215
|
+
self._requisitar("POST", "/auth/sair")
|
|
208
216
|
except ErroDatamais:
|
|
209
217
|
pass
|
|
210
218
|
self._token = None
|
|
@@ -243,7 +251,7 @@ class ClienteDatamais:
|
|
|
243
251
|
cabecalhos: dict[str, str] = dict(kwargs.pop("headers", None) or {})
|
|
244
252
|
cabecalhos.update(self._cabecalhos_auth(token))
|
|
245
253
|
resposta = self._http.request(method, path, headers=cabecalhos, **kwargs)
|
|
246
|
-
if resposta
|
|
254
|
+
if _falhou(resposta):
|
|
247
255
|
raise de_resposta(resposta)
|
|
248
256
|
return resposta
|
|
249
257
|
|
|
@@ -257,7 +265,7 @@ class ClienteDatamais:
|
|
|
257
265
|
cabecalhos = {"Accept": "text/event-stream", **self._cabecalhos_auth(None)}
|
|
258
266
|
tempos = httpx.Timeout(self._timeout, read=max(self._timeout, _ESPERA_MINIMA_EVENTO))
|
|
259
267
|
with self._http.stream("GET", caminho, headers=cabecalhos, timeout=tempos) as resposta:
|
|
260
|
-
if resposta
|
|
268
|
+
if _falhou(resposta):
|
|
261
269
|
resposta.read()
|
|
262
270
|
raise de_resposta(resposta)
|
|
263
271
|
for evento in ler_eventos(resposta.iter_text()):
|
|
@@ -319,5 +327,18 @@ def _sincronizando(resposta: httpx.Response) -> bool:
|
|
|
319
327
|
return resposta.headers.get("X-Fonte-Sincronizando") == "1"
|
|
320
328
|
|
|
321
329
|
|
|
330
|
+
def _falhou(resposta: httpx.Response) -> bool:
|
|
331
|
+
if resposta.status_code == httpx.codes.NOT_MODIFIED:
|
|
332
|
+
return False
|
|
333
|
+
return resposta.is_redirect or resposta.is_error
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
def _rota(modelo: str, *segmentos: str) -> str:
|
|
337
|
+
for segmento in segmentos:
|
|
338
|
+
if segmento in ("", ".", ".."):
|
|
339
|
+
raise ErroSegmentoInvalido(segmento)
|
|
340
|
+
return modelo.format(*(quote(segmento, safe="") for segmento in segmentos))
|
|
341
|
+
|
|
342
|
+
|
|
322
343
|
def _relacoes_de(body: dict[str, Any]) -> list[RelacaoFonte]:
|
|
323
344
|
return [RelacaoFonte.de_payload(relacao) for relacao in body.get("relacoes") or []]
|
|
@@ -21,6 +21,15 @@ class ErroSessaoObrigatoria(ErroDatamais):
|
|
|
21
21
|
self.acao = acao
|
|
22
22
|
|
|
23
23
|
|
|
24
|
+
class ErroSegmentoInvalido(ErroDatamais):
|
|
25
|
+
def __init__(self, segmento: str) -> None:
|
|
26
|
+
super().__init__(
|
|
27
|
+
f"segmento de rota inválido: {segmento!r}; "
|
|
28
|
+
"grupo e slug não podem ser vazios nem iguais a '.' ou '..'"
|
|
29
|
+
)
|
|
30
|
+
self.segmento = segmento
|
|
31
|
+
|
|
32
|
+
|
|
24
33
|
class ErroAPI(ErroDatamais):
|
|
25
34
|
def __init__(self, status: int, detalhe: str, erros: list[dict[str, Any]]) -> None:
|
|
26
35
|
super().__init__(f"HTTP {status}: {detalhe}")
|
|
@@ -29,6 +38,18 @@ class ErroAPI(ErroDatamais):
|
|
|
29
38
|
self.erros = erros
|
|
30
39
|
|
|
31
40
|
|
|
41
|
+
class ErroRedirecionamento(ErroAPI):
|
|
42
|
+
def __init__(self, status: int, destino: str) -> None:
|
|
43
|
+
para_onde = f"para {destino}" if destino else "sem cabeçalho Location"
|
|
44
|
+
super().__init__(
|
|
45
|
+
status,
|
|
46
|
+
f"redirecionamento {para_onde}; o cliente não segue redirecionamentos, para nunca "
|
|
47
|
+
"reenviar as credenciais, então a URL base precisa apontar para o endereço final",
|
|
48
|
+
[],
|
|
49
|
+
)
|
|
50
|
+
self.destino = destino
|
|
51
|
+
|
|
52
|
+
|
|
32
53
|
class ErroAutenticacao(ErroAPI): ...
|
|
33
54
|
|
|
34
55
|
|
|
@@ -58,6 +79,8 @@ _ERROS_POR_STATUS: dict[int, type[ErroAPI]] = {
|
|
|
58
79
|
|
|
59
80
|
|
|
60
81
|
def de_resposta(resposta: httpx.Response) -> ErroAPI:
|
|
82
|
+
if resposta.is_redirect:
|
|
83
|
+
return ErroRedirecionamento(resposta.status_code, resposta.headers.get("Location", ""))
|
|
61
84
|
detalhe, lista_erros = _detalhes_problema(resposta)
|
|
62
85
|
tipo_erro = _ERROS_POR_STATUS.get(resposta.status_code, ErroAPI)
|
|
63
86
|
return tipo_erro(resposta.status_code, detalhe, lista_erros)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: datamais-api
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Cliente Python da API DataMais, feito para bots de carga de dados.
|
|
5
5
|
Author: SECONV-RR
|
|
6
6
|
License-Expression: LicenseRef-Proprietary
|
|
@@ -46,10 +46,13 @@ precedência sobre elas:
|
|
|
46
46
|
|
|
47
47
|
| Variável | Propósito |
|
|
48
48
|
| --- | --- |
|
|
49
|
-
| `DATAMAIS_BASE_URL` | URL base da API (ex.: `https://
|
|
49
|
+
| `DATAMAIS_BASE_URL` | URL base da API, com o prefixo do proxy reverso (ex.: `https://datamais.example/api/v1`) |
|
|
50
50
|
| `DATAMAIS_API_KEY` | Segredo da chave de API (`dmk_...`) com concessões `view`/`manage` nas fontes alvo |
|
|
51
51
|
|
|
52
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`.
|
|
53
56
|
`DATAMAIS_API_KEY` é opcional: omita-a para clientes somente-sessão, que
|
|
54
57
|
passam um `token` de sessão em vez de uma chave de máquina (veja
|
|
55
58
|
[Sessão de usuário](#sessão-de-usuário)).
|
|
@@ -75,7 +78,7 @@ with ClienteDatamais() as cliente:
|
|
|
75
78
|
```
|
|
76
79
|
|
|
77
80
|
`substituir_dados_fonte` substitui atomicamente o catálogo de colunas e as
|
|
78
|
-
linhas da fonte (`PUT /
|
|
81
|
+
linhas da fonte (`PUT /grupos/{grupo}/fontes/{slug}/dados`); a chave de API
|
|
79
82
|
precisa possuir `dataset:<grupo>:<slug>:manage` (ou a equivalente em nível de
|
|
80
83
|
grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
|
|
81
84
|
`dataset:<grupo>:<slug>:view`, a menos que a fonte seja pública.
|
|
@@ -83,7 +86,7 @@ grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
|
|
|
83
86
|
`Coluna(..., escondida=True)` mantém os valores em cada linha sem mostrar a
|
|
84
87
|
coluna ao usuário, o que serve para chaves técnicas que ligam fontes.
|
|
85
88
|
|
|
86
|
-
`criar_fonte` cadastra uma fonte em um grupo (`POST /
|
|
89
|
+
`criar_fonte` cadastra uma fonte em um grupo (`POST /grupos/{grupo}/fontes`),
|
|
87
90
|
para que um bot de carga possa criar a fonte que está prestes a preencher:
|
|
88
91
|
|
|
89
92
|
```python
|
|
@@ -108,7 +111,7 @@ ou sem dono, como `ErroValidacao` (`422`).
|
|
|
108
111
|
|
|
109
112
|
`consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
|
|
110
113
|
no servidor e devolve só o resultado
|
|
111
|
-
(`POST /
|
|
114
|
+
(`POST /grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
|
|
112
115
|
leva um corpo, mas não altera nada. Ela pede a mesma permissão de
|
|
113
116
|
`obter_dados_fonte` e aceita as mesmas credenciais: chave de API, sessão ou
|
|
114
117
|
nenhuma, no caso de fontes públicas.
|
|
@@ -223,9 +226,9 @@ with ClienteDatamais() as cliente:
|
|
|
223
226
|
|
|
224
227
|
| Método | Rota | Credenciais |
|
|
225
228
|
| --- | --- | --- |
|
|
226
|
-
| `acompanhar_dados_fonte(grupo, slug)` | `GET /
|
|
227
|
-
| `acompanhar_dados_fonte_independente(slug)` | `GET /
|
|
228
|
-
| `acompanhar_dados_painel(grupo, slug)` | `GET /
|
|
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) |
|
|
229
232
|
|
|
230
233
|
Cada rota pede a mesma permissão da leitura comum que corresponde a ela.
|
|
231
234
|
|
|
@@ -258,7 +261,7 @@ chamada. O servidor encerra o fluxo no máximo no tempo limite de busca dele
|
|
|
258
261
|
item, ou o `timeout` do cliente, se ele for maior.
|
|
259
262
|
|
|
260
263
|
`obter_dados_painel` lê de uma vez os dados de todas as entradas de fonte de um
|
|
261
|
-
painel (`GET /
|
|
264
|
+
painel (`GET /grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
|
|
262
265
|
pelo id da entrada, `negado` lista as entradas que o chamador não pode ler e
|
|
263
266
|
`relacoes` traz as relações entre as entradas como `RelacaoPainel`. Essa
|
|
264
267
|
leitura também dispara a atualização das fontes do painel, e `sincronizando`
|
|
@@ -335,9 +338,10 @@ com a renderização: a inferência não tem como adivinhar `money`, `date`,
|
|
|
335
338
|
|
|
336
339
|
## Erros
|
|
337
340
|
|
|
338
|
-
Toda resposta não-2xx levanta uma exceção tipada carregando
|
|
339
|
-
`detalhe` e a lista estruturada `erros` da API:
|
|
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:
|
|
340
343
|
|
|
344
|
+
- `ErroRedirecionamento` (3xx, menos 304)
|
|
341
345
|
- `ErroAutenticacao` (401) — chave ausente, inválida, expirada ou revogada
|
|
342
346
|
- `ErroProibido` (403) — a chave não possui a permissão exigida
|
|
343
347
|
- `ErroNaoEncontrado` (404) — fonte desconhecida (grupo, slug)
|
|
@@ -347,7 +351,22 @@ Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
|
|
|
347
351
|
- `ErroAPI` — qualquer outro status não-2xx
|
|
348
352
|
|
|
349
353
|
Todas são subclasses de `ErroAPI`, que por sua vez é subclasse de
|
|
350
|
-
`ErroDatamais`, ao lado de `ErroConfigAusente` e
|
|
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`.
|
|
351
370
|
|
|
352
371
|
## Consumidores
|
|
353
372
|
|
|
@@ -14,12 +14,13 @@ from datamais_api import (
|
|
|
14
14
|
ErroAPI,
|
|
15
15
|
ErroNaoEncontrado,
|
|
16
16
|
ErroProibido,
|
|
17
|
+
ErroRedirecionamento,
|
|
17
18
|
ErroSessaoObrigatoria,
|
|
18
19
|
FalhaSincronizacao,
|
|
19
20
|
RelacaoPainel,
|
|
20
21
|
)
|
|
21
22
|
|
|
22
|
-
URL_BASE = "https://api.example.com"
|
|
23
|
+
URL_BASE = "https://api.example.com/api/v1"
|
|
23
24
|
CHAVE_API = "dmk_secret"
|
|
24
25
|
|
|
25
26
|
Manipulador = Callable[[httpx.Request], httpx.Response]
|
|
@@ -92,7 +93,7 @@ def test_acompanhar_dados_fonte_entrega_cada_versao_e_para_no_fim() -> None:
|
|
|
92
93
|
|
|
93
94
|
[requisicao] = capturadas
|
|
94
95
|
assert requisicao.method == "GET"
|
|
95
|
-
assert str(requisicao.url) == f"{URL_BASE}/
|
|
96
|
+
assert str(requisicao.url) == f"{URL_BASE}/grupos/geral/fontes/programas/dados/eventos"
|
|
96
97
|
assert requisicao.headers["X-API-Chave"] == CHAVE_API
|
|
97
98
|
assert requisicao.headers["Accept"] == "text/event-stream"
|
|
98
99
|
assert len(eventos) == 2
|
|
@@ -198,6 +199,25 @@ def test_acompanhar_dados_fonte_levanta_o_erro_http_antes_do_primeiro_evento(
|
|
|
198
199
|
assert exc.value.detalhe == detalhe
|
|
199
200
|
|
|
200
201
|
|
|
202
|
+
def test_acompanhar_dados_fonte_levanta_redirecionamento_sem_seguir_o_destino() -> None:
|
|
203
|
+
capturadas: list[httpx.Request] = []
|
|
204
|
+
|
|
205
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
206
|
+
capturadas.append(requisicao)
|
|
207
|
+
return httpx.Response(302, headers={"Location": "https://outro-host.example/eventos"})
|
|
208
|
+
|
|
209
|
+
with cliente_com(manipulador) as cliente:
|
|
210
|
+
eventos = cliente.acompanhar_dados_fonte("geral", "programas")
|
|
211
|
+
with pytest.raises(ErroRedirecionamento) as exc:
|
|
212
|
+
next(eventos)
|
|
213
|
+
|
|
214
|
+
[requisicao] = capturadas
|
|
215
|
+
assert str(requisicao.url) == f"{URL_BASE}/grupos/geral/fontes/programas/dados/eventos"
|
|
216
|
+
assert requisicao.headers["X-API-Chave"] == CHAVE_API
|
|
217
|
+
assert exc.value.status == 302
|
|
218
|
+
assert exc.value.destino == "https://outro-host.example/eventos"
|
|
219
|
+
|
|
220
|
+
|
|
201
221
|
@pytest.mark.parametrize(("timeout", "leitura"), [(30.0, 90.0), (5.0, 90.0), (120.0, 120.0)])
|
|
202
222
|
def test_acompanhar_espera_cada_evento_por_no_minimo_noventa_segundos(
|
|
203
223
|
timeout: float, leitura: float
|
|
@@ -230,7 +250,7 @@ def test_acompanhar_dados_fonte_independente_usa_o_token_da_sessao() -> None:
|
|
|
230
250
|
[dados] = list(cliente.acompanhar_dados_fonte_independente("tabela-global"))
|
|
231
251
|
|
|
232
252
|
[requisicao] = capturadas
|
|
233
|
-
assert str(requisicao.url) == f"{URL_BASE}/
|
|
253
|
+
assert str(requisicao.url) == f"{URL_BASE}/fontes/independentes/tabela-global/dados/eventos"
|
|
234
254
|
assert requisicao.headers["Authorization"] == "Bearer tok-1"
|
|
235
255
|
assert "X-API-Chave" not in requisicao.headers
|
|
236
256
|
assert isinstance(dados, DadosPainel)
|
|
@@ -284,7 +304,7 @@ def test_acompanhar_dados_painel_entrega_as_entradas_e_a_falha_por_entrada() ->
|
|
|
284
304
|
anterior, atual, falha = list(cliente.acompanhar_dados_painel("geral", "convenios"))
|
|
285
305
|
|
|
286
306
|
[requisicao] = capturadas
|
|
287
|
-
assert str(requisicao.url) == f"{URL_BASE}/
|
|
307
|
+
assert str(requisicao.url) == f"{URL_BASE}/grupos/geral/paineis/convenios/dados/eventos"
|
|
288
308
|
assert requisicao.headers["X-API-Chave"] == CHAVE_API
|
|
289
309
|
assert isinstance(anterior, DadosFontesPainel)
|
|
290
310
|
assert anterior.sincronizando is True
|
|
@@ -328,7 +348,7 @@ def test_obter_dados_painel_le_entradas_e_o_aviso_de_sincronizacao() -> None:
|
|
|
328
348
|
|
|
329
349
|
[requisicao] = capturadas
|
|
330
350
|
assert requisicao.method == "GET"
|
|
331
|
-
assert str(requisicao.url) == f"{URL_BASE}/
|
|
351
|
+
assert str(requisicao.url) == f"{URL_BASE}/grupos/geral/paineis/convenios/dados"
|
|
332
352
|
assert requisicao.headers["X-API-Chave"] == CHAVE_API
|
|
333
353
|
assert dados.sincronizando is True
|
|
334
354
|
assert dados.fontes["e1"].atualizado_em == datetime(2026, 10, 27, 10, 0, tzinfo=UTC)
|
|
@@ -11,6 +11,7 @@ from datamais_api import (
|
|
|
11
11
|
Coluna,
|
|
12
12
|
ColunaRelacao,
|
|
13
13
|
Consulta,
|
|
14
|
+
DefinicaoPainel,
|
|
14
15
|
DestinoRelacao,
|
|
15
16
|
DirecaoOrdem,
|
|
16
17
|
ErroAPI,
|
|
@@ -18,6 +19,8 @@ from datamais_api import (
|
|
|
18
19
|
ErroConflito,
|
|
19
20
|
ErroNaoEncontrado,
|
|
20
21
|
ErroProibido,
|
|
22
|
+
ErroRedirecionamento,
|
|
23
|
+
ErroSegmentoInvalido,
|
|
21
24
|
ErroServicoIndisponivel,
|
|
22
25
|
ErroSessaoObrigatoria,
|
|
23
26
|
ErroValidacao,
|
|
@@ -31,7 +34,7 @@ from datamais_api import (
|
|
|
31
34
|
TipoColuna,
|
|
32
35
|
)
|
|
33
36
|
|
|
34
|
-
URL_BASE = "https://api.example.com"
|
|
37
|
+
URL_BASE = "https://api.example.com/api/v1"
|
|
35
38
|
CHAVE_API = "dmk_secret"
|
|
36
39
|
|
|
37
40
|
Manipulador = Callable[[httpx.Request], httpx.Response]
|
|
@@ -63,7 +66,7 @@ def test_obter_dados_fonte_envia_chave_e_analisa_payload() -> None:
|
|
|
63
66
|
with cliente_com(manipulador) as cliente:
|
|
64
67
|
dados = cliente.obter_dados_fonte("geral", "programas")
|
|
65
68
|
|
|
66
|
-
assert visto["url"] == f"{URL_BASE}/
|
|
69
|
+
assert visto["url"] == f"{URL_BASE}/grupos/geral/fontes/programas/dados"
|
|
67
70
|
assert visto["chave"] == CHAVE_API
|
|
68
71
|
assert dados.atualizado_em is not None
|
|
69
72
|
assert dados.atualizado_em.year == 2026
|
|
@@ -141,7 +144,7 @@ def test_consultar_fonte_faz_post_so_dos_campos_definidos() -> None:
|
|
|
141
144
|
cliente.consultar_fonte("seconv", "convenios", consulta)
|
|
142
145
|
|
|
143
146
|
assert capturado["method"] == "POST"
|
|
144
|
-
assert capturado["url"] == f"{URL_BASE}/
|
|
147
|
+
assert capturado["url"] == f"{URL_BASE}/grupos/seconv/fontes/convenios/consulta"
|
|
145
148
|
assert capturado["chave"] == CHAVE_API
|
|
146
149
|
assert capturado["body"] == {
|
|
147
150
|
"filtros": [
|
|
@@ -356,7 +359,7 @@ def test_substituir_dados_fonte_faz_put_do_conteudo_completo() -> None:
|
|
|
356
359
|
cliente.substituir_dados_fonte("geral", "programas", colunas, linhas)
|
|
357
360
|
|
|
358
361
|
assert capturado["method"] == "PUT"
|
|
359
|
-
assert capturado["url"] == f"{URL_BASE}/
|
|
362
|
+
assert capturado["url"] == f"{URL_BASE}/grupos/geral/fontes/programas/dados"
|
|
360
363
|
assert capturado["body"] == {
|
|
361
364
|
"colunas": [
|
|
362
365
|
{
|
|
@@ -402,7 +405,7 @@ def test_criar_fonte_faz_post_da_entrada_de_catalogo() -> None:
|
|
|
402
405
|
)
|
|
403
406
|
|
|
404
407
|
assert capturado["method"] == "POST"
|
|
405
|
-
assert capturado["url"] == f"{URL_BASE}/
|
|
408
|
+
assert capturado["url"] == f"{URL_BASE}/grupos/seconv/fontes"
|
|
406
409
|
assert capturado["chave"] == CHAVE_API
|
|
407
410
|
assert capturado["body"] == {
|
|
408
411
|
"slug": "programas",
|
|
@@ -467,7 +470,7 @@ def test_obter_relacoes_fonte_analisa_o_payload() -> None:
|
|
|
467
470
|
with cliente_com(manipulador) as cliente:
|
|
468
471
|
relacoes = cliente.obter_relacoes_fonte("seconv", "extratos")
|
|
469
472
|
|
|
470
|
-
assert visto["url"] == f"{URL_BASE}/
|
|
473
|
+
assert visto["url"] == f"{URL_BASE}/grupos/seconv/fontes/extratos/relacoes"
|
|
471
474
|
assert visto["chave"] == CHAVE_API
|
|
472
475
|
assert len(relacoes) == 1
|
|
473
476
|
assert relacoes[0].destino.fonte == "contas"
|
|
@@ -515,7 +518,7 @@ def test_definir_relacoes_fonte_faz_put_do_conjunto_completo() -> None:
|
|
|
515
518
|
devolvidas = cliente.definir_relacoes_fonte("seconv", "extratos", relacoes)
|
|
516
519
|
|
|
517
520
|
assert capturado["method"] == "PUT"
|
|
518
|
-
assert capturado["url"] == f"{URL_BASE}/
|
|
521
|
+
assert capturado["url"] == f"{URL_BASE}/grupos/seconv/fontes/extratos/relacoes"
|
|
519
522
|
assert capturado["body"] == {
|
|
520
523
|
"relacoes": [
|
|
521
524
|
{
|
|
@@ -569,7 +572,7 @@ def test_definir_relacoes_fonte_independente_usa_o_token_da_sessao() -> None:
|
|
|
569
572
|
with cliente:
|
|
570
573
|
cliente.definir_relacoes_fonte_independente("tabela-global", [])
|
|
571
574
|
|
|
572
|
-
assert capturado["url"] == f"{URL_BASE}/
|
|
575
|
+
assert capturado["url"] == f"{URL_BASE}/fontes/independentes/tabela-global/relacoes"
|
|
573
576
|
assert capturado["autorizacao"] == "Bearer tok-1"
|
|
574
577
|
|
|
575
578
|
|
|
@@ -613,3 +616,240 @@ def test_status_nao_mapeado_lanca_erro_api_generico_com_detalhe_reserva() -> Non
|
|
|
613
616
|
|
|
614
617
|
assert exc.value.status == 500
|
|
615
618
|
assert exc.value.erros == []
|
|
619
|
+
|
|
620
|
+
|
|
621
|
+
DESTINO_EXTERNO = "https://outro-host.example/coleta"
|
|
622
|
+
|
|
623
|
+
|
|
624
|
+
def redirecionando(status: int, capturadas: list[httpx.Request]) -> Manipulador:
|
|
625
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
626
|
+
capturadas.append(requisicao)
|
|
627
|
+
return httpx.Response(status, headers={"Location": DESTINO_EXTERNO})
|
|
628
|
+
|
|
629
|
+
return manipulador
|
|
630
|
+
|
|
631
|
+
|
|
632
|
+
def test_redirecionamento_com_chave_levanta_erro_sem_seguir_o_destino() -> None:
|
|
633
|
+
capturadas: list[httpx.Request] = []
|
|
634
|
+
|
|
635
|
+
with (
|
|
636
|
+
cliente_com(redirecionando(302, capturadas)) as cliente,
|
|
637
|
+
pytest.raises(ErroRedirecionamento) as exc,
|
|
638
|
+
):
|
|
639
|
+
cliente.obter_dados_fonte("geral", "programas")
|
|
640
|
+
|
|
641
|
+
[requisicao] = capturadas
|
|
642
|
+
assert str(requisicao.url) == f"{URL_BASE}/grupos/geral/fontes/programas/dados"
|
|
643
|
+
assert requisicao.headers["X-API-Chave"] == CHAVE_API
|
|
644
|
+
assert exc.value.status == 302
|
|
645
|
+
assert exc.value.destino == DESTINO_EXTERNO
|
|
646
|
+
assert str(exc.value) == (
|
|
647
|
+
f"HTTP 302: redirecionamento para {DESTINO_EXTERNO}; o cliente não segue "
|
|
648
|
+
"redirecionamentos, para nunca reenviar as credenciais, então a URL base precisa "
|
|
649
|
+
"apontar para o endereço final"
|
|
650
|
+
)
|
|
651
|
+
|
|
652
|
+
|
|
653
|
+
def test_redirecionamento_com_token_levanta_erro_sem_seguir_o_destino() -> None:
|
|
654
|
+
capturadas: list[httpx.Request] = []
|
|
655
|
+
cliente = ClienteDatamais(
|
|
656
|
+
URL_BASE, token="tok-1", transport=httpx.MockTransport(redirecionando(302, capturadas))
|
|
657
|
+
)
|
|
658
|
+
|
|
659
|
+
with cliente, pytest.raises(ErroRedirecionamento) as exc:
|
|
660
|
+
cliente.eu()
|
|
661
|
+
|
|
662
|
+
[requisicao] = capturadas
|
|
663
|
+
assert str(requisicao.url) == f"{URL_BASE}/auth/eu"
|
|
664
|
+
assert requisicao.headers["Authorization"] == "Bearer tok-1"
|
|
665
|
+
assert exc.value.status == 302
|
|
666
|
+
assert exc.value.destino == DESTINO_EXTERNO
|
|
667
|
+
|
|
668
|
+
|
|
669
|
+
def test_redirecionamento_307_de_um_put_levanta_erro_sem_reenviar_o_corpo() -> None:
|
|
670
|
+
capturadas: list[httpx.Request] = []
|
|
671
|
+
colunas = [Coluna("nome", "Nome")]
|
|
672
|
+
|
|
673
|
+
with (
|
|
674
|
+
cliente_com(redirecionando(307, capturadas)) as cliente,
|
|
675
|
+
pytest.raises(ErroRedirecionamento) as exc,
|
|
676
|
+
):
|
|
677
|
+
cliente.substituir_dados_fonte("geral", "programas", colunas, [{"nome": "Obra"}])
|
|
678
|
+
|
|
679
|
+
[requisicao] = capturadas
|
|
680
|
+
assert requisicao.method == "PUT"
|
|
681
|
+
assert str(requisicao.url) == f"{URL_BASE}/grupos/geral/fontes/programas/dados"
|
|
682
|
+
assert exc.value.status == 307
|
|
683
|
+
assert exc.value.destino == DESTINO_EXTERNO
|
|
684
|
+
|
|
685
|
+
|
|
686
|
+
@pytest.mark.parametrize("status", [300, 301, 303, 308])
|
|
687
|
+
def test_todo_3xx_menos_o_304_levanta_redirecionamento_mesmo_sem_location(status: int) -> None:
|
|
688
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
689
|
+
return httpx.Response(status)
|
|
690
|
+
|
|
691
|
+
with cliente_com(manipulador) as cliente, pytest.raises(ErroAPI) as exc:
|
|
692
|
+
cliente.obter_dados_fonte("geral", "programas")
|
|
693
|
+
|
|
694
|
+
assert isinstance(exc.value, ErroRedirecionamento)
|
|
695
|
+
assert exc.value.status == status
|
|
696
|
+
assert exc.value.destino == ""
|
|
697
|
+
assert str(exc.value).startswith(f"HTTP {status}: redirecionamento sem cabeçalho Location;")
|
|
698
|
+
|
|
699
|
+
|
|
700
|
+
def test_httpx_resolve_segmentos_de_ponto_no_caminho() -> None:
|
|
701
|
+
caminhos: list[str] = []
|
|
702
|
+
|
|
703
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
704
|
+
caminhos.append(requisicao.url.path)
|
|
705
|
+
return httpx.Response(204)
|
|
706
|
+
|
|
707
|
+
with httpx.Client(base_url=URL_BASE, transport=httpx.MockTransport(manipulador)) as http:
|
|
708
|
+
http.get("/grupos/geral/fontes/../../usuarios/dados")
|
|
709
|
+
|
|
710
|
+
assert caminhos == ["/api/v1/grupos/usuarios/dados"]
|
|
711
|
+
|
|
712
|
+
|
|
713
|
+
@pytest.mark.parametrize(
|
|
714
|
+
("slug", "segmento"),
|
|
715
|
+
[
|
|
716
|
+
("a/b", "a%2Fb"),
|
|
717
|
+
("a?b", "a%3Fb"),
|
|
718
|
+
("a#b", "a%23b"),
|
|
719
|
+
("a%b", "a%25b"),
|
|
720
|
+
("a b", "a%20b"),
|
|
721
|
+
("../../usuarios", "..%2F..%2Fusuarios"),
|
|
722
|
+
],
|
|
723
|
+
)
|
|
724
|
+
def test_slug_vai_na_rota_como_um_unico_segmento_codificado(slug: str, segmento: str) -> None:
|
|
725
|
+
capturadas: list[httpx.Request] = []
|
|
726
|
+
|
|
727
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
728
|
+
capturadas.append(requisicao)
|
|
729
|
+
return httpx.Response(200, json={"colunas": [], "linhas": []})
|
|
730
|
+
|
|
731
|
+
with cliente_com(manipulador) as cliente:
|
|
732
|
+
cliente.obter_dados_fonte("geral", slug)
|
|
733
|
+
|
|
734
|
+
[requisicao] = capturadas
|
|
735
|
+
assert str(requisicao.url) == f"{URL_BASE}/grupos/geral/fontes/{segmento}/dados"
|
|
736
|
+
|
|
737
|
+
|
|
738
|
+
@pytest.mark.parametrize(
|
|
739
|
+
("chamada", "rota"),
|
|
740
|
+
[
|
|
741
|
+
pytest.param(
|
|
742
|
+
lambda c: c.obter_dados_fonte("../g", "a/b"),
|
|
743
|
+
"/grupos/..%2Fg/fontes/a%2Fb/dados",
|
|
744
|
+
id="obter_dados_fonte",
|
|
745
|
+
),
|
|
746
|
+
pytest.param(
|
|
747
|
+
lambda c: c.consultar_fonte("../g", "a/b"),
|
|
748
|
+
"/grupos/..%2Fg/fontes/a%2Fb/consulta",
|
|
749
|
+
id="consultar_fonte",
|
|
750
|
+
),
|
|
751
|
+
pytest.param(
|
|
752
|
+
lambda c: c.substituir_dados_fonte("../g", "a/b", [], []),
|
|
753
|
+
"/grupos/..%2Fg/fontes/a%2Fb/dados",
|
|
754
|
+
id="substituir_dados_fonte",
|
|
755
|
+
),
|
|
756
|
+
pytest.param(
|
|
757
|
+
lambda c: c.criar_fonte("../g", "a/b", "Programas"),
|
|
758
|
+
"/grupos/..%2Fg/fontes",
|
|
759
|
+
id="criar_fonte",
|
|
760
|
+
),
|
|
761
|
+
pytest.param(
|
|
762
|
+
lambda c: c.obter_relacoes_fonte("../g", "a/b"),
|
|
763
|
+
"/grupos/..%2Fg/fontes/a%2Fb/relacoes",
|
|
764
|
+
id="obter_relacoes_fonte",
|
|
765
|
+
),
|
|
766
|
+
pytest.param(
|
|
767
|
+
lambda c: c.definir_relacoes_fonte("../g", "a/b", []),
|
|
768
|
+
"/grupos/..%2Fg/fontes/a%2Fb/relacoes",
|
|
769
|
+
id="definir_relacoes_fonte",
|
|
770
|
+
),
|
|
771
|
+
pytest.param(
|
|
772
|
+
lambda c: c.obter_relacoes_fonte_independente("a/b"),
|
|
773
|
+
"/fontes/independentes/a%2Fb/relacoes",
|
|
774
|
+
id="obter_relacoes_fonte_independente",
|
|
775
|
+
),
|
|
776
|
+
pytest.param(
|
|
777
|
+
lambda c: c.definir_relacoes_fonte_independente("a/b", []),
|
|
778
|
+
"/fontes/independentes/a%2Fb/relacoes",
|
|
779
|
+
id="definir_relacoes_fonte_independente",
|
|
780
|
+
),
|
|
781
|
+
pytest.param(
|
|
782
|
+
lambda c: c.obter_dados_painel("../g", "a/b"),
|
|
783
|
+
"/grupos/..%2Fg/paineis/a%2Fb/dados",
|
|
784
|
+
id="obter_dados_painel",
|
|
785
|
+
),
|
|
786
|
+
pytest.param(
|
|
787
|
+
lambda c: c.obter_layout("../g", "a/b"),
|
|
788
|
+
"/grupos/..%2Fg/paineis/a%2Fb/layout",
|
|
789
|
+
id="obter_layout",
|
|
790
|
+
),
|
|
791
|
+
pytest.param(
|
|
792
|
+
lambda c: c.substituir_layout("../g", "a/b", DefinicaoPainel()),
|
|
793
|
+
"/grupos/..%2Fg/paineis/a%2Fb/layout",
|
|
794
|
+
id="substituir_layout",
|
|
795
|
+
),
|
|
796
|
+
pytest.param(
|
|
797
|
+
lambda c: list(c.acompanhar_dados_fonte("../g", "a/b")),
|
|
798
|
+
"/grupos/..%2Fg/fontes/a%2Fb/dados/eventos",
|
|
799
|
+
id="acompanhar_dados_fonte",
|
|
800
|
+
),
|
|
801
|
+
pytest.param(
|
|
802
|
+
lambda c: list(c.acompanhar_dados_fonte_independente("a/b")),
|
|
803
|
+
"/fontes/independentes/a%2Fb/dados/eventos",
|
|
804
|
+
id="acompanhar_dados_fonte_independente",
|
|
805
|
+
),
|
|
806
|
+
pytest.param(
|
|
807
|
+
lambda c: list(c.acompanhar_dados_painel("../g", "a/b")),
|
|
808
|
+
"/grupos/..%2Fg/paineis/a%2Fb/dados/eventos",
|
|
809
|
+
id="acompanhar_dados_painel",
|
|
810
|
+
),
|
|
811
|
+
],
|
|
812
|
+
)
|
|
813
|
+
def test_toda_rota_leva_grupo_e_slug_como_segmentos_codificados(
|
|
814
|
+
chamada: Callable[[ClienteDatamais], object], rota: str
|
|
815
|
+
) -> None:
|
|
816
|
+
capturadas: list[httpx.Request] = []
|
|
817
|
+
|
|
818
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
819
|
+
capturadas.append(requisicao)
|
|
820
|
+
return httpx.Response(403)
|
|
821
|
+
|
|
822
|
+
cliente = ClienteDatamais(URL_BASE, token="tok-1", transport=httpx.MockTransport(manipulador))
|
|
823
|
+
with cliente, pytest.raises(ErroProibido):
|
|
824
|
+
chamada(cliente)
|
|
825
|
+
|
|
826
|
+
[requisicao] = capturadas
|
|
827
|
+
assert str(requisicao.url) == f"{URL_BASE}{rota}"
|
|
828
|
+
|
|
829
|
+
|
|
830
|
+
@pytest.mark.parametrize("segmento", ["", ".", ".."])
|
|
831
|
+
def test_segmento_vazio_ou_de_ponto_levanta_erro_antes_de_qualquer_requisicao(
|
|
832
|
+
segmento: str,
|
|
833
|
+
) -> None:
|
|
834
|
+
capturadas: list[httpx.Request] = []
|
|
835
|
+
|
|
836
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
837
|
+
capturadas.append(requisicao)
|
|
838
|
+
return httpx.Response(204)
|
|
839
|
+
|
|
840
|
+
with cliente_com(manipulador) as cliente:
|
|
841
|
+
with pytest.raises(ErroSegmentoInvalido) as no_grupo:
|
|
842
|
+
cliente.obter_dados_fonte(segmento, "programas")
|
|
843
|
+
with pytest.raises(ErroSegmentoInvalido) as no_slug:
|
|
844
|
+
cliente.substituir_dados_fonte("geral", segmento, [], [])
|
|
845
|
+
with pytest.raises(ErroSegmentoInvalido) as no_fluxo:
|
|
846
|
+
cliente.acompanhar_dados_painel("geral", segmento)
|
|
847
|
+
|
|
848
|
+
assert capturadas == []
|
|
849
|
+
assert no_grupo.value.segmento == segmento
|
|
850
|
+
assert no_slug.value.segmento == segmento
|
|
851
|
+
assert no_fluxo.value.segmento == segmento
|
|
852
|
+
assert str(no_grupo.value) == (
|
|
853
|
+
f"segmento de rota inválido: {segmento!r}; "
|
|
854
|
+
"grupo e slug não podem ser vazios nem iguais a '.' ou '..'"
|
|
855
|
+
)
|
|
@@ -91,7 +91,7 @@ def test_forma_do_payload_da_definicao() -> None:
|
|
|
91
91
|
|
|
92
92
|
def test_obter_layout_analisa_definicao() -> None:
|
|
93
93
|
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
94
|
-
assert requisicao.url.path == "/
|
|
94
|
+
assert requisicao.url.path == "/grupos/geral/paineis/convenios/layout"
|
|
95
95
|
return httpx.Response(200, json=definicao_exemplo().para_payload())
|
|
96
96
|
|
|
97
97
|
with cliente_com(manipulador, chave_api=CHAVE_API) as cliente:
|
|
@@ -139,7 +139,7 @@ def test_substituir_layout_envia_bearer_e_corpo() -> None:
|
|
|
139
139
|
cliente.substituir_layout("geral", "convenios", definicao_exemplo())
|
|
140
140
|
|
|
141
141
|
assert capturado["method"] == "PUT"
|
|
142
|
-
assert capturado["path"] == "/
|
|
142
|
+
assert capturado["path"] == "/grupos/geral/paineis/convenios/layout"
|
|
143
143
|
assert capturado["auth"] == f"Bearer {TOKEN}"
|
|
144
144
|
assert capturado["body"] == definicao_exemplo().para_payload()
|
|
145
145
|
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|