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.
Files changed (23) hide show
  1. {datamais_api-0.4.0/src/datamais_api.egg-info → datamais_api-0.5.0}/PKG-INFO +31 -12
  2. {datamais_api-0.4.0 → datamais_api-0.5.0}/README.md +30 -11
  3. {datamais_api-0.4.0 → datamais_api-0.5.0}/pyproject.toml +1 -1
  4. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/__init__.py +5 -1
  5. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/cliente.py +39 -18
  6. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/erros.py +23 -0
  7. {datamais_api-0.4.0 → datamais_api-0.5.0/src/datamais_api.egg-info}/PKG-INFO +31 -12
  8. {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_acompanhar.py +25 -5
  9. {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_cliente.py +248 -8
  10. {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_layout.py +2 -2
  11. {datamais_api-0.4.0 → datamais_api-0.5.0}/LICENSE +0 -0
  12. {datamais_api-0.4.0 → datamais_api-0.5.0}/setup.cfg +0 -0
  13. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/config.py +0 -0
  14. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/eventos.py +0 -0
  15. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/modelos.py +0 -0
  16. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api/py.typed +0 -0
  17. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/SOURCES.txt +0 -0
  18. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/dependency_links.txt +0 -0
  19. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/requires.txt +0 -0
  20. {datamais_api-0.4.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/top_level.txt +0 -0
  21. {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_config.py +0 -0
  22. {datamais_api-0.4.0 → datamais_api-0.5.0}/tests/test_eventos.py +0 -0
  23. {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.4.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://api.datamais.example`) |
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 /v1/grupos/{grupo}/fontes/{slug}/dados`); a chave de API
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 /v1/grupos/{grupo}/fontes`),
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 /v1/grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
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 /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
+ | `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 /v1/grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
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 `status`,
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 `ErroSessaoObrigatoria`.
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://api.datamais.example`) |
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 /v1/grupos/{grupo}/fontes/{slug}/dados`); a chave de API
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 /v1/grupos/{grupo}/fontes`),
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 /v1/grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
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 /v1/grupos/{grupo}/fontes/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (fonte pública) |
208
- | `acompanhar_dados_fonte_independente(slug)` | `GET /v1/fontes/independentes/{slug}/dados/eventos` | só sessão |
209
- | `acompanhar_dados_painel(grupo, slug)` | `GET /v1/grupos/{grupo}/paineis/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (painel público) |
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 /v1/grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
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 `status`,
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 `ErroSessaoObrigatoria`.
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
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "datamais-api"
3
- version = "0.4.0"
3
+ version = "0.5.0"
4
4
  description = "Cliente Python da API DataMais, feito para bots de carga de dados."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.13"
@@ -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.4.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", f"/v1/grupos/{grupo}/fontes/{slug}/dados"))
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
- f"/v1/grupos/{grupo}/fontes/{slug}/dados/eventos", _dados_de_evento
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(f"/v1/fontes/independentes/{slug}/dados/eventos", _dados_de_evento)
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", f"/v1/grupos/{grupo}/paineis/{slug}/dados")
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
- f"/v1/grupos/{grupo}/paineis/{slug}/dados/eventos", _dados_painel_de_evento
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
- f"/v1/grupos/{grupo}/fontes/{slug}/consulta",
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", f"/v1/grupos/{grupo}/fontes/{slug}/dados", json=payload)
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", f"/v1/grupos/{grupo}/fontes", json=payload).json()
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(f"/v1/grupos/{grupo}/fontes/{slug}/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(f"/v1/grupos/{grupo}/fontes/{slug}/relacoes", 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(f"/v1/fontes/independentes/{slug}/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(f"/v1/fontes/independentes/{slug}/relacoes", 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", f"/v1/grupos/{grupo}/paineis/{slug}/layout").json()
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
- f"/v1/grupos/{grupo}/paineis/{slug}/layout",
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", "/v1/auth/eu", token=token).json()
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", "/v1/auth/sair")
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.is_error:
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.is_error:
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.4.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://api.datamais.example`) |
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 /v1/grupos/{grupo}/fontes/{slug}/dados`); a chave de API
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 /v1/grupos/{grupo}/fontes`),
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 /v1/grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
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 /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
+ | `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 /v1/grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
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 `status`,
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 `ErroSessaoObrigatoria`.
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}/v1/grupos/geral/fontes/programas/dados/eventos"
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}/v1/fontes/independentes/tabela-global/dados/eventos"
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}/v1/grupos/geral/paineis/convenios/dados/eventos"
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}/v1/grupos/geral/paineis/convenios/dados"
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}/v1/grupos/geral/fontes/programas/dados"
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}/v1/grupos/seconv/fontes/convenios/consulta"
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}/v1/grupos/geral/fontes/programas/dados"
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}/v1/grupos/seconv/fontes"
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}/v1/grupos/seconv/fontes/extratos/relacoes"
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}/v1/grupos/seconv/fontes/extratos/relacoes"
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}/v1/fontes/independentes/tabela-global/relacoes"
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 == "/v1/grupos/geral/paineis/convenios/layout"
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"] == "/v1/grupos/geral/paineis/convenios/layout"
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