datamais-api 0.4.0__tar.gz → 0.6.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.6.0}/PKG-INFO +93 -15
  2. {datamais_api-0.4.0 → datamais_api-0.6.0}/README.md +92 -14
  3. {datamais_api-0.4.0 → datamais_api-0.6.0}/pyproject.toml +1 -1
  4. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api/__init__.py +5 -1
  5. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api/cliente.py +64 -32
  6. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api/erros.py +23 -0
  7. {datamais_api-0.4.0 → datamais_api-0.6.0/src/datamais_api.egg-info}/PKG-INFO +93 -15
  8. {datamais_api-0.4.0 → datamais_api-0.6.0}/tests/test_acompanhar.py +25 -5
  9. {datamais_api-0.4.0 → datamais_api-0.6.0}/tests/test_cliente.py +383 -15
  10. {datamais_api-0.4.0 → datamais_api-0.6.0}/tests/test_layout.py +2 -2
  11. {datamais_api-0.4.0 → datamais_api-0.6.0}/tests/test_pandas.py +27 -0
  12. {datamais_api-0.4.0 → datamais_api-0.6.0}/LICENSE +0 -0
  13. {datamais_api-0.4.0 → datamais_api-0.6.0}/setup.cfg +0 -0
  14. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api/config.py +0 -0
  15. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api/eventos.py +0 -0
  16. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api/modelos.py +0 -0
  17. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api/py.typed +0 -0
  18. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api.egg-info/SOURCES.txt +0 -0
  19. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api.egg-info/dependency_links.txt +0 -0
  20. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api.egg-info/requires.txt +0 -0
  21. {datamais_api-0.4.0 → datamais_api-0.6.0}/src/datamais_api.egg-info/top_level.txt +0 -0
  22. {datamais_api-0.4.0 → datamais_api-0.6.0}/tests/test_config.py +0 -0
  23. {datamais_api-0.4.0 → datamais_api-0.6.0}/tests/test_eventos.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.6.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
@@ -104,11 +107,70 @@ existir e ter dono — uma chave não é um usuário, então ela nunca pode cria
104
107
  grupo. Uma fonte que já existe volta como `ErroConflito`; um grupo inexistente
105
108
  ou sem dono, como `ErroValidacao` (`422`).
106
109
 
110
+ ## Fontes independentes
111
+
112
+ Uma fonte independente não pertence a um grupo. Ela tem um slug global e pode
113
+ ser anexada a vários grupos, que a leem pelo caminho do grupo. Quem escreve
114
+ nela usa as rotas `/fontes/independentes/{slug}/...`, com uma chave de API que
115
+ tenha `independent:<slug>:manage` ou com uma sessão que tenha
116
+ `datasets:independent`, `dev` ou `admin`.
117
+
118
+ | Método | Rota | Credenciais |
119
+ | --- | --- | --- |
120
+ | `substituir_dados_fonte_independente(slug, colunas, linhas)` | `PUT /fontes/independentes/{slug}/dados` | chave de API ou sessão |
121
+ | `substituir_dados_fonte_independente_de_dataframe(slug, frame, colunas=None)` | `PUT /fontes/independentes/{slug}/dados` | chave de API ou sessão |
122
+ | `obter_relacoes_fonte_independente(slug)` | `GET /fontes/independentes/{slug}/relacoes` | chave de API ou sessão |
123
+ | `definir_relacoes_fonte_independente(slug, relacoes)` | `PUT /fontes/independentes/{slug}/relacoes` | chave de API ou sessão |
124
+
125
+ ```python
126
+ from datamais_api import (
127
+ ClienteDatamais,
128
+ Coluna,
129
+ ColunaRelacao,
130
+ DestinoRelacao,
131
+ RelacaoFonte,
132
+ TipoColuna,
133
+ )
134
+
135
+ colunas = [
136
+ Coluna("ibge", "IBGE", escondida=True),
137
+ Coluna("municipio", "Município", filtravel=True),
138
+ Coluna("populacao", "População", TipoColuna.INTEIRO),
139
+ ]
140
+ linhas = [{"ibge": "1400100", "municipio": "Boa Vista", "populacao": 413486}]
141
+ relacoes = [
142
+ RelacaoFonte(
143
+ destino=DestinoRelacao(fonte="municipios", independente=True),
144
+ colunas=[ColunaRelacao(origem="ibge", destino="ibge")],
145
+ ),
146
+ ]
147
+
148
+ with ClienteDatamais() as cliente:
149
+ cliente.substituir_dados_fonte_independente("municipios", colunas, linhas)
150
+ cliente.definir_relacoes_fonte_independente("convenios-estaduais", relacoes)
151
+ ```
152
+
153
+ `substituir_dados_fonte_independente` troca de uma vez o catálogo de colunas e
154
+ as linhas da fonte, com o mesmo corpo de `substituir_dados_fonte`, e a versão
155
+ nova vale para todos os grupos em que a fonte está anexada. A variante
156
+ `_de_dataframe` recebe um DataFrame e infere o catálogo como
157
+ `substituir_dados_fonte_de_dataframe` (veja [pandas](#pandas)).
158
+
159
+ `definir_relacoes_fonte_independente` troca o conjunto inteiro de relações da
160
+ fonte e devolve o que a API gravou; uma lista vazia remove todas. Como a fonte
161
+ não tem grupo, o destino precisa vir com `grupo` explícito ou com
162
+ `independente=True`. As colunas citadas precisam existir nas duas fontes, então
163
+ carregue os dados delas antes de declarar a relação. Os corpos e as respostas
164
+ são os mesmos de `obter_relacoes_fonte` e `definir_relacoes_fonte`.
165
+
166
+ Uma chave sem a permissão da fonte recebe `ErroProibido` (403), e um slug que
167
+ não existe, `ErroNaoEncontrado` (404).
168
+
107
169
  ## Consultas no servidor
108
170
 
109
171
  `consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
110
172
  no servidor e devolve só o resultado
111
- (`POST /v1/grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
173
+ (`POST /grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
112
174
  leva um corpo, mas não altera nada. Ela pede a mesma permissão de
113
175
  `obter_dados_fonte` e aceita as mesmas credenciais: chave de API, sessão ou
114
176
  nenhuma, no caso de fontes públicas.
@@ -223,9 +285,9 @@ with ClienteDatamais() as cliente:
223
285
 
224
286
  | Método | Rota | Credenciais |
225
287
  | --- | --- | --- |
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) |
288
+ | `acompanhar_dados_fonte(grupo, slug)` | `GET /grupos/{grupo}/fontes/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (fonte pública) |
289
+ | `acompanhar_dados_fonte_independente(slug)` | `GET /fontes/independentes/{slug}/dados/eventos` | só sessão |
290
+ | `acompanhar_dados_painel(grupo, slug)` | `GET /grupos/{grupo}/paineis/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (painel público) |
229
291
 
230
292
  Cada rota pede a mesma permissão da leitura comum que corresponde a ela.
231
293
 
@@ -258,7 +320,7 @@ chamada. O servidor encerra o fluxo no máximo no tempo limite de busca dele
258
320
  item, ou o `timeout` do cliente, se ele for maior.
259
321
 
260
322
  `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
323
+ painel (`GET /grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
262
324
  pelo id da entrada, `negado` lista as entradas que o chamador não pode ler e
263
325
  `relacoes` traz as relações entre as entradas como `RelacaoPainel`. Essa
264
326
  leitura também dispara a atualização das fontes do painel, e `sincronizando`
@@ -301,9 +363,9 @@ with ClienteDatamais(token=token_da_sessao) as cliente:
301
363
  ```
302
364
 
303
365
  A autenticação é resolvida a cada requisição: o `token` vai como
304
- `Authorization: Bearer` e, sem ele, vai o `X-API-Chave`. As rotas que só
305
- aceitam sessão (as de fontes independentes) levantam `ErroSessaoObrigatoria`
306
- sem token, antes de fazer a requisição.
366
+ `Authorization: Bearer` e, sem ele, vai o `X-API-Chave`. A única rota que só
367
+ aceita sessão, `acompanhar_dados_fonte_independente`, levanta
368
+ `ErroSessaoObrigatoria` sem token, antes de fazer a requisição.
307
369
 
308
370
  `eu` devolve o `Usuario` da sessão, ou `None` quando ela não vale mais.
309
371
  `eu(token)` usa outro token só naquela chamada. `sair` revoga a sessão na API
@@ -335,9 +397,10 @@ com a renderização: a inferência não tem como adivinhar `money`, `date`,
335
397
 
336
398
  ## Erros
337
399
 
338
- Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
339
- `detalhe` e a lista estruturada `erros` da API:
400
+ Toda resposta não-2xx, menos o 304, levanta uma exceção tipada carregando
401
+ `status`, `detalhe` e a lista estruturada `erros` da API:
340
402
 
403
+ - `ErroRedirecionamento` (3xx, menos 304)
341
404
  - `ErroAutenticacao` (401) — chave ausente, inválida, expirada ou revogada
342
405
  - `ErroProibido` (403) — a chave não possui a permissão exigida
343
406
  - `ErroNaoEncontrado` (404) — fonte desconhecida (grupo, slug)
@@ -347,7 +410,22 @@ Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
347
410
  - `ErroAPI` — qualquer outro status não-2xx
348
411
 
349
412
  Todas são subclasses de `ErroAPI`, que por sua vez é subclasse de
350
- `ErroDatamais`, ao lado de `ErroConfigAusente` e `ErroSessaoObrigatoria`.
413
+ `ErroDatamais`, ao lado de `ErroConfigAusente`, `ErroSessaoObrigatoria` e
414
+ `ErroSegmentoInvalido`.
415
+
416
+ O cliente não segue redirecionamentos, porque seguir um 3xx reenviaria a chave
417
+ de API ou o token de sessão para o endereço do `Location`, que pode ser outro
418
+ host. Qualquer 3xx, menos o 304, levanta `ErroRedirecionamento`, com o `status`
419
+ e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
420
+ cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
421
+ endereço final, por exemplo trocando `http://` por `https://`.
422
+
423
+ Cada `grupo` e `slug` entra na rota como um único segmento codificado, então
424
+ `/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um `grupo` ou `slug`
425
+ vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
426
+ requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
427
+ nele, então a chamada poderia ir para outra rota com as suas credenciais. O
428
+ valor recusado fica em `segmento`.
351
429
 
352
430
  ## Consumidores
353
431
 
@@ -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
@@ -85,11 +88,70 @@ existir e ter dono — uma chave não é um usuário, então ela nunca pode cria
85
88
  grupo. Uma fonte que já existe volta como `ErroConflito`; um grupo inexistente
86
89
  ou sem dono, como `ErroValidacao` (`422`).
87
90
 
91
+ ## Fontes independentes
92
+
93
+ Uma fonte independente não pertence a um grupo. Ela tem um slug global e pode
94
+ ser anexada a vários grupos, que a leem pelo caminho do grupo. Quem escreve
95
+ nela usa as rotas `/fontes/independentes/{slug}/...`, com uma chave de API que
96
+ tenha `independent:<slug>:manage` ou com uma sessão que tenha
97
+ `datasets:independent`, `dev` ou `admin`.
98
+
99
+ | Método | Rota | Credenciais |
100
+ | --- | --- | --- |
101
+ | `substituir_dados_fonte_independente(slug, colunas, linhas)` | `PUT /fontes/independentes/{slug}/dados` | chave de API ou sessão |
102
+ | `substituir_dados_fonte_independente_de_dataframe(slug, frame, colunas=None)` | `PUT /fontes/independentes/{slug}/dados` | chave de API ou sessão |
103
+ | `obter_relacoes_fonte_independente(slug)` | `GET /fontes/independentes/{slug}/relacoes` | chave de API ou sessão |
104
+ | `definir_relacoes_fonte_independente(slug, relacoes)` | `PUT /fontes/independentes/{slug}/relacoes` | chave de API ou sessão |
105
+
106
+ ```python
107
+ from datamais_api import (
108
+ ClienteDatamais,
109
+ Coluna,
110
+ ColunaRelacao,
111
+ DestinoRelacao,
112
+ RelacaoFonte,
113
+ TipoColuna,
114
+ )
115
+
116
+ colunas = [
117
+ Coluna("ibge", "IBGE", escondida=True),
118
+ Coluna("municipio", "Município", filtravel=True),
119
+ Coluna("populacao", "População", TipoColuna.INTEIRO),
120
+ ]
121
+ linhas = [{"ibge": "1400100", "municipio": "Boa Vista", "populacao": 413486}]
122
+ relacoes = [
123
+ RelacaoFonte(
124
+ destino=DestinoRelacao(fonte="municipios", independente=True),
125
+ colunas=[ColunaRelacao(origem="ibge", destino="ibge")],
126
+ ),
127
+ ]
128
+
129
+ with ClienteDatamais() as cliente:
130
+ cliente.substituir_dados_fonte_independente("municipios", colunas, linhas)
131
+ cliente.definir_relacoes_fonte_independente("convenios-estaduais", relacoes)
132
+ ```
133
+
134
+ `substituir_dados_fonte_independente` troca de uma vez o catálogo de colunas e
135
+ as linhas da fonte, com o mesmo corpo de `substituir_dados_fonte`, e a versão
136
+ nova vale para todos os grupos em que a fonte está anexada. A variante
137
+ `_de_dataframe` recebe um DataFrame e infere o catálogo como
138
+ `substituir_dados_fonte_de_dataframe` (veja [pandas](#pandas)).
139
+
140
+ `definir_relacoes_fonte_independente` troca o conjunto inteiro de relações da
141
+ fonte e devolve o que a API gravou; uma lista vazia remove todas. Como a fonte
142
+ não tem grupo, o destino precisa vir com `grupo` explícito ou com
143
+ `independente=True`. As colunas citadas precisam existir nas duas fontes, então
144
+ carregue os dados delas antes de declarar a relação. Os corpos e as respostas
145
+ são os mesmos de `obter_relacoes_fonte` e `definir_relacoes_fonte`.
146
+
147
+ Uma chave sem a permissão da fonte recebe `ErroProibido` (403), e um slug que
148
+ não existe, `ErroNaoEncontrado` (404).
149
+
88
150
  ## Consultas no servidor
89
151
 
90
152
  `consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
91
153
  no servidor e devolve só o resultado
92
- (`POST /v1/grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
154
+ (`POST /grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
93
155
  leva um corpo, mas não altera nada. Ela pede a mesma permissão de
94
156
  `obter_dados_fonte` e aceita as mesmas credenciais: chave de API, sessão ou
95
157
  nenhuma, no caso de fontes públicas.
@@ -204,9 +266,9 @@ with ClienteDatamais() as cliente:
204
266
 
205
267
  | Método | Rota | Credenciais |
206
268
  | --- | --- | --- |
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) |
269
+ | `acompanhar_dados_fonte(grupo, slug)` | `GET /grupos/{grupo}/fontes/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (fonte pública) |
270
+ | `acompanhar_dados_fonte_independente(slug)` | `GET /fontes/independentes/{slug}/dados/eventos` | só sessão |
271
+ | `acompanhar_dados_painel(grupo, slug)` | `GET /grupos/{grupo}/paineis/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (painel público) |
210
272
 
211
273
  Cada rota pede a mesma permissão da leitura comum que corresponde a ela.
212
274
 
@@ -239,7 +301,7 @@ chamada. O servidor encerra o fluxo no máximo no tempo limite de busca dele
239
301
  item, ou o `timeout` do cliente, se ele for maior.
240
302
 
241
303
  `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
304
+ painel (`GET /grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
243
305
  pelo id da entrada, `negado` lista as entradas que o chamador não pode ler e
244
306
  `relacoes` traz as relações entre as entradas como `RelacaoPainel`. Essa
245
307
  leitura também dispara a atualização das fontes do painel, e `sincronizando`
@@ -282,9 +344,9 @@ with ClienteDatamais(token=token_da_sessao) as cliente:
282
344
  ```
283
345
 
284
346
  A autenticação é resolvida a cada requisição: o `token` vai como
285
- `Authorization: Bearer` e, sem ele, vai o `X-API-Chave`. As rotas que só
286
- aceitam sessão (as de fontes independentes) levantam `ErroSessaoObrigatoria`
287
- sem token, antes de fazer a requisição.
347
+ `Authorization: Bearer` e, sem ele, vai o `X-API-Chave`. A única rota que só
348
+ aceita sessão, `acompanhar_dados_fonte_independente`, levanta
349
+ `ErroSessaoObrigatoria` sem token, antes de fazer a requisição.
288
350
 
289
351
  `eu` devolve o `Usuario` da sessão, ou `None` quando ela não vale mais.
290
352
  `eu(token)` usa outro token só naquela chamada. `sair` revoga a sessão na API
@@ -316,9 +378,10 @@ com a renderização: a inferência não tem como adivinhar `money`, `date`,
316
378
 
317
379
  ## Erros
318
380
 
319
- Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
320
- `detalhe` e a lista estruturada `erros` da API:
381
+ Toda resposta não-2xx, menos o 304, levanta uma exceção tipada carregando
382
+ `status`, `detalhe` e a lista estruturada `erros` da API:
321
383
 
384
+ - `ErroRedirecionamento` (3xx, menos 304)
322
385
  - `ErroAutenticacao` (401) — chave ausente, inválida, expirada ou revogada
323
386
  - `ErroProibido` (403) — a chave não possui a permissão exigida
324
387
  - `ErroNaoEncontrado` (404) — fonte desconhecida (grupo, slug)
@@ -328,7 +391,22 @@ Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
328
391
  - `ErroAPI` — qualquer outro status não-2xx
329
392
 
330
393
  Todas são subclasses de `ErroAPI`, que por sua vez é subclasse de
331
- `ErroDatamais`, ao lado de `ErroConfigAusente` e `ErroSessaoObrigatoria`.
394
+ `ErroDatamais`, ao lado de `ErroConfigAusente`, `ErroSessaoObrigatoria` e
395
+ `ErroSegmentoInvalido`.
396
+
397
+ O cliente não segue redirecionamentos, porque seguir um 3xx reenviaria a chave
398
+ de API ou o token de sessão para o endereço do `Location`, que pode ser outro
399
+ host. Qualquer 3xx, menos o 304, levanta `ErroRedirecionamento`, com o `status`
400
+ e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
401
+ cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
402
+ endereço final, por exemplo trocando `http://` por `https://`.
403
+
404
+ Cada `grupo` e `slug` entra na rota como um único segmento codificado, então
405
+ `/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um `grupo` ou `slug`
406
+ vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
407
+ requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
408
+ nele, então a chamada poderia ir para outra rota com as suas credenciais. O
409
+ valor recusado fica em `segmento`.
332
410
 
333
411
  ## Consumidores
334
412
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "datamais-api"
3
- version = "0.4.0"
3
+ version = "0.6.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.6.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
  )
@@ -114,11 +119,7 @@ class ClienteDatamais:
114
119
  def substituir_dados_fonte(
115
120
  self, grupo: str, slug: str, colunas: list[Coluna], linhas: list[Linha]
116
121
  ) -> None:
117
- payload: dict[str, Any] = {
118
- "colunas": [coluna.para_payload() for coluna in colunas],
119
- "linhas": linhas,
120
- }
121
- self._requisitar("PUT", f"/v1/grupos/{grupo}/fontes/{slug}/dados", json=payload)
122
+ self._substituir_dados(_rota("/grupos/{}/fontes/{}/dados", grupo, slug), colunas, linhas)
122
123
 
123
124
  def substituir_dados_fonte_de_dataframe(
124
125
  self,
@@ -127,12 +128,24 @@ class ClienteDatamais:
127
128
  frame: pd.DataFrame,
128
129
  colunas: list[Coluna] | None = None,
129
130
  ) -> None:
130
- self.substituir_dados_fonte(
131
- grupo,
132
- slug,
133
- colunas if colunas is not None else colunas_de_dataframe(frame),
134
- linhas_de_dataframe(frame),
135
- )
131
+ self.substituir_dados_fonte(grupo, slug, *_conteudo_de_dataframe(frame, colunas))
132
+
133
+ def substituir_dados_fonte_independente(
134
+ self, slug: str, colunas: list[Coluna], linhas: list[Linha]
135
+ ) -> None:
136
+ self._substituir_dados(_rota("/fontes/independentes/{}/dados", slug), colunas, linhas)
137
+
138
+ def substituir_dados_fonte_independente_de_dataframe(
139
+ self, slug: str, frame: pd.DataFrame, colunas: list[Coluna] | None = None
140
+ ) -> None:
141
+ self.substituir_dados_fonte_independente(slug, *_conteudo_de_dataframe(frame, colunas))
142
+
143
+ def _substituir_dados(self, caminho: str, colunas: list[Coluna], linhas: list[Linha]) -> None:
144
+ payload: dict[str, Any] = {
145
+ "colunas": [coluna.para_payload() for coluna in colunas],
146
+ "linhas": linhas,
147
+ }
148
+ self._requisitar("PUT", caminho, json=payload)
136
149
 
137
150
  def criar_fonte(
138
151
  self,
@@ -149,28 +162,26 @@ class ClienteDatamais:
149
162
  }
150
163
  if descricao:
151
164
  payload["descricao"] = descricao
152
- body = self._requisitar("POST", f"/v1/grupos/{grupo}/fontes", json=payload).json()
165
+ body = self._requisitar("POST", _rota("/grupos/{}/fontes", grupo), json=payload).json()
153
166
  return Fonte.de_payload(body["fonte"])
154
167
 
155
168
  def obter_relacoes_fonte(self, grupo: str, slug: str) -> list[RelacaoFonte]:
156
- return self._obter_relacoes(f"/v1/grupos/{grupo}/fontes/{slug}/relacoes")
169
+ return self._obter_relacoes(_rota("/grupos/{}/fontes/{}/relacoes", grupo, slug))
157
170
 
158
171
  def definir_relacoes_fonte(
159
172
  self, grupo: str, slug: str, relacoes: list[RelacaoFonte]
160
173
  ) -> list[RelacaoFonte]:
161
- return self._definir_relacoes(f"/v1/grupos/{grupo}/fontes/{slug}/relacoes", relacoes)
174
+ return self._definir_relacoes(
175
+ _rota("/grupos/{}/fontes/{}/relacoes", grupo, slug), relacoes
176
+ )
162
177
 
163
178
  def obter_relacoes_fonte_independente(self, slug: str) -> list[RelacaoFonte]:
164
- if not self._token:
165
- raise ErroSessaoObrigatoria("Obter as relações de uma fonte independente")
166
- return self._obter_relacoes(f"/v1/fontes/independentes/{slug}/relacoes")
179
+ return self._obter_relacoes(_rota("/fontes/independentes/{}/relacoes", slug))
167
180
 
168
181
  def definir_relacoes_fonte_independente(
169
182
  self, slug: str, relacoes: list[RelacaoFonte]
170
183
  ) -> list[RelacaoFonte]:
171
- if not self._token:
172
- raise ErroSessaoObrigatoria("Definir as relações de uma fonte independente")
173
- return self._definir_relacoes(f"/v1/fontes/independentes/{slug}/relacoes", relacoes)
184
+ return self._definir_relacoes(_rota("/fontes/independentes/{}/relacoes", slug), relacoes)
174
185
 
175
186
  def _obter_relacoes(self, caminho: str) -> list[RelacaoFonte]:
176
187
  body = self._requisitar("GET", caminho).json()
@@ -182,8 +193,9 @@ class ClienteDatamais:
182
193
  return _relacoes_de(body)
183
194
 
184
195
  def obter_layout(self, grupo: str, slug: str) -> DefinicaoPainel | None:
196
+ caminho = _rota("/grupos/{}/paineis/{}/layout", grupo, slug)
185
197
  try:
186
- body = self._requisitar("GET", f"/v1/grupos/{grupo}/paineis/{slug}/layout").json()
198
+ body = self._requisitar("GET", caminho).json()
187
199
  except ErroNaoEncontrado:
188
200
  return None
189
201
  return DefinicaoPainel.de_payload(body)
@@ -191,20 +203,20 @@ class ClienteDatamais:
191
203
  def substituir_layout(self, grupo: str, slug: str, definicao: DefinicaoPainel) -> None:
192
204
  self._requisitar(
193
205
  "PUT",
194
- f"/v1/grupos/{grupo}/paineis/{slug}/layout",
206
+ _rota("/grupos/{}/paineis/{}/layout", grupo, slug),
195
207
  json=definicao.para_payload(),
196
208
  )
197
209
 
198
210
  def eu(self, token: str | None = None) -> Usuario | None:
199
211
  try:
200
- body = self._requisitar("GET", "/v1/auth/eu", token=token).json()
212
+ body = self._requisitar("GET", "/auth/eu", token=token).json()
201
213
  except ErroAutenticacao:
202
214
  return None
203
215
  return Usuario.de_payload(body)
204
216
 
205
217
  def sair(self) -> None:
206
218
  try:
207
- self._requisitar("POST", "/v1/auth/sair")
219
+ self._requisitar("POST", "/auth/sair")
208
220
  except ErroDatamais:
209
221
  pass
210
222
  self._token = None
@@ -243,7 +255,7 @@ class ClienteDatamais:
243
255
  cabecalhos: dict[str, str] = dict(kwargs.pop("headers", None) or {})
244
256
  cabecalhos.update(self._cabecalhos_auth(token))
245
257
  resposta = self._http.request(method, path, headers=cabecalhos, **kwargs)
246
- if resposta.is_error:
258
+ if _falhou(resposta):
247
259
  raise de_resposta(resposta)
248
260
  return resposta
249
261
 
@@ -257,7 +269,7 @@ class ClienteDatamais:
257
269
  cabecalhos = {"Accept": "text/event-stream", **self._cabecalhos_auth(None)}
258
270
  tempos = httpx.Timeout(self._timeout, read=max(self._timeout, _ESPERA_MINIMA_EVENTO))
259
271
  with self._http.stream("GET", caminho, headers=cabecalhos, timeout=tempos) as resposta:
260
- if resposta.is_error:
272
+ if _falhou(resposta):
261
273
  resposta.read()
262
274
  raise de_resposta(resposta)
263
275
  for evento in ler_eventos(resposta.iter_text()):
@@ -319,5 +331,25 @@ def _sincronizando(resposta: httpx.Response) -> bool:
319
331
  return resposta.headers.get("X-Fonte-Sincronizando") == "1"
320
332
 
321
333
 
334
+ def _falhou(resposta: httpx.Response) -> bool:
335
+ if resposta.status_code == httpx.codes.NOT_MODIFIED:
336
+ return False
337
+ return resposta.is_redirect or resposta.is_error
338
+
339
+
340
+ def _rota(modelo: str, *segmentos: str) -> str:
341
+ for segmento in segmentos:
342
+ if segmento in ("", ".", ".."):
343
+ raise ErroSegmentoInvalido(segmento)
344
+ return modelo.format(*(quote(segmento, safe="") for segmento in segmentos))
345
+
346
+
347
+ def _conteudo_de_dataframe(
348
+ frame: pd.DataFrame, colunas: list[Coluna] | None
349
+ ) -> tuple[list[Coluna], list[Linha]]:
350
+ catalogo = colunas if colunas is not None else colunas_de_dataframe(frame)
351
+ return catalogo, linhas_de_dataframe(frame)
352
+
353
+
322
354
  def _relacoes_de(body: dict[str, Any]) -> list[RelacaoFonte]:
323
355
  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)