datamais-api 0.5.0__tar.gz → 0.7.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {datamais_api-0.5.0/src/datamais_api.egg-info → datamais_api-0.7.0}/PKG-INFO +104 -7
- {datamais_api-0.5.0 → datamais_api-0.7.0}/README.md +103 -6
- {datamais_api-0.5.0 → datamais_api-0.7.0}/pyproject.toml +1 -1
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/__init__.py +3 -1
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/cliente.py +36 -15
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/modelos.py +21 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0/src/datamais_api.egg-info}/PKG-INFO +104 -7
- {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_cliente.py +239 -7
- {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_pandas.py +27 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/LICENSE +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/setup.cfg +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/config.py +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/erros.py +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/eventos.py +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/py.typed +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/SOURCES.txt +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/dependency_links.txt +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/requires.txt +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/top_level.txt +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_acompanhar.py +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_config.py +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_eventos.py +0 -0
- {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_layout.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: datamais-api
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.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
|
|
@@ -107,6 +107,103 @@ existir e ter dono — uma chave não é um usuário, então ela nunca pode cria
|
|
|
107
107
|
grupo. Uma fonte que já existe volta como `ErroConflito`; um grupo inexistente
|
|
108
108
|
ou sem dono, como `ErroValidacao` (`422`).
|
|
109
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
|
+
|
|
169
|
+
## Fontes em coleções
|
|
170
|
+
|
|
171
|
+
Uma coleção reúne as fontes independentes que uma mesma carga alimenta. Uma
|
|
172
|
+
chave de API com `collection:<colecao>:manage` cria fontes independentes na
|
|
173
|
+
coleção e substitui os dados e as relações de todas elas, inclusive das criadas
|
|
174
|
+
depois da concessão. A carga não precisa de uma permissão nova para cada slug.
|
|
175
|
+
|
|
176
|
+
| Método | Rota | Credenciais |
|
|
177
|
+
| --- | --- | --- |
|
|
178
|
+
| `garantir_fonte_colecao(colecao, slug, nome, *, descricao="")` | `PUT /colecoes/{colecao}/fontes/{slug}` | chave de API ou sessão |
|
|
179
|
+
|
|
180
|
+
```python
|
|
181
|
+
from datamais_api import ClienteDatamais
|
|
182
|
+
|
|
183
|
+
with ClienteDatamais() as cliente:
|
|
184
|
+
fonte = cliente.garantir_fonte_colecao(
|
|
185
|
+
"programas", "propostas", "Propostas", descricao="Propostas de convênio"
|
|
186
|
+
)
|
|
187
|
+
cliente.substituir_dados_fonte_independente(fonte.slug, colunas, linhas)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
`garantir_fonte_colecao` é a chamada que uma carga faz antes de enviar os
|
|
191
|
+
dados, e devolve uma `FonteGarantida` (`id`, `slug`, `nome`, `descricao`,
|
|
192
|
+
`colecao`, `criada`). `criada` vale `True` quando a chamada criou a fonte (201)
|
|
193
|
+
e `False` quando ela já estava na coleção (200). Nesse segundo caso a fonte
|
|
194
|
+
fica com o nome e a descrição enviados: repetir a chamada com os mesmos valores
|
|
195
|
+
não muda nada, mas omitir `descricao` apaga a descrição que ela tinha. A fonte
|
|
196
|
+
criada herda o dono da coleção e só aparece para as pessoas depois que alguém a
|
|
197
|
+
anexa a um grupo.
|
|
198
|
+
|
|
199
|
+
Se o slug já pertence a uma fonte independente de outra coleção, ou de nenhuma,
|
|
200
|
+
a chamada levanta `ErroConflito` (409) com o lugar do slug no `detalhe`. Uma
|
|
201
|
+
chave sem `collection:<colecao>:manage` recebe `ErroProibido` (403). Com
|
|
202
|
+
sessão, que precisa de `datasets:independent`, `dev` ou `admin`, uma coleção
|
|
203
|
+
que não existe levanta `ErroNaoEncontrado` (404). Um slug reservado, ou fora do
|
|
204
|
+
padrão `^[a-z0-9][a-z0-9_-]*$` com até 63 caracteres, levanta `ErroValidacao`
|
|
205
|
+
(422).
|
|
206
|
+
|
|
110
207
|
## Consultas no servidor
|
|
111
208
|
|
|
112
209
|
`consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
|
|
@@ -304,9 +401,9 @@ with ClienteDatamais(token=token_da_sessao) as cliente:
|
|
|
304
401
|
```
|
|
305
402
|
|
|
306
403
|
A autenticação é resolvida a cada requisição: o `token` vai como
|
|
307
|
-
`Authorization: Bearer` e, sem ele, vai o `X-API-Chave`.
|
|
308
|
-
|
|
309
|
-
sem token, antes de fazer a requisição.
|
|
404
|
+
`Authorization: Bearer` e, sem ele, vai o `X-API-Chave`. A única rota que só
|
|
405
|
+
aceita sessão, `acompanhar_dados_fonte_independente`, levanta
|
|
406
|
+
`ErroSessaoObrigatoria` sem token, antes de fazer a requisição.
|
|
310
407
|
|
|
311
408
|
`eu` devolve o `Usuario` da sessão, ou `None` quando ela não vale mais.
|
|
312
409
|
`eu(token)` usa outro token só naquela chamada. `sair` revoga a sessão na API
|
|
@@ -361,9 +458,9 @@ e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
|
|
|
361
458
|
cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
|
|
362
459
|
endereço final, por exemplo trocando `http://` por `https://`.
|
|
363
460
|
|
|
364
|
-
Cada `grupo` e `slug` entra na rota como um único segmento
|
|
365
|
-
`/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um
|
|
366
|
-
vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
|
|
461
|
+
Cada `grupo`, `colecao` e `slug` entra na rota como um único segmento
|
|
462
|
+
codificado, então `/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um
|
|
463
|
+
`grupo`, `colecao` ou `slug` vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
|
|
367
464
|
requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
|
|
368
465
|
nele, então a chamada poderia ir para outra rota com as suas credenciais. O
|
|
369
466
|
valor recusado fica em `segmento`.
|
|
@@ -88,6 +88,103 @@ existir e ter dono — uma chave não é um usuário, então ela nunca pode cria
|
|
|
88
88
|
grupo. Uma fonte que já existe volta como `ErroConflito`; um grupo inexistente
|
|
89
89
|
ou sem dono, como `ErroValidacao` (`422`).
|
|
90
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
|
+
|
|
150
|
+
## Fontes em coleções
|
|
151
|
+
|
|
152
|
+
Uma coleção reúne as fontes independentes que uma mesma carga alimenta. Uma
|
|
153
|
+
chave de API com `collection:<colecao>:manage` cria fontes independentes na
|
|
154
|
+
coleção e substitui os dados e as relações de todas elas, inclusive das criadas
|
|
155
|
+
depois da concessão. A carga não precisa de uma permissão nova para cada slug.
|
|
156
|
+
|
|
157
|
+
| Método | Rota | Credenciais |
|
|
158
|
+
| --- | --- | --- |
|
|
159
|
+
| `garantir_fonte_colecao(colecao, slug, nome, *, descricao="")` | `PUT /colecoes/{colecao}/fontes/{slug}` | chave de API ou sessão |
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
from datamais_api import ClienteDatamais
|
|
163
|
+
|
|
164
|
+
with ClienteDatamais() as cliente:
|
|
165
|
+
fonte = cliente.garantir_fonte_colecao(
|
|
166
|
+
"programas", "propostas", "Propostas", descricao="Propostas de convênio"
|
|
167
|
+
)
|
|
168
|
+
cliente.substituir_dados_fonte_independente(fonte.slug, colunas, linhas)
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
`garantir_fonte_colecao` é a chamada que uma carga faz antes de enviar os
|
|
172
|
+
dados, e devolve uma `FonteGarantida` (`id`, `slug`, `nome`, `descricao`,
|
|
173
|
+
`colecao`, `criada`). `criada` vale `True` quando a chamada criou a fonte (201)
|
|
174
|
+
e `False` quando ela já estava na coleção (200). Nesse segundo caso a fonte
|
|
175
|
+
fica com o nome e a descrição enviados: repetir a chamada com os mesmos valores
|
|
176
|
+
não muda nada, mas omitir `descricao` apaga a descrição que ela tinha. A fonte
|
|
177
|
+
criada herda o dono da coleção e só aparece para as pessoas depois que alguém a
|
|
178
|
+
anexa a um grupo.
|
|
179
|
+
|
|
180
|
+
Se o slug já pertence a uma fonte independente de outra coleção, ou de nenhuma,
|
|
181
|
+
a chamada levanta `ErroConflito` (409) com o lugar do slug no `detalhe`. Uma
|
|
182
|
+
chave sem `collection:<colecao>:manage` recebe `ErroProibido` (403). Com
|
|
183
|
+
sessão, que precisa de `datasets:independent`, `dev` ou `admin`, uma coleção
|
|
184
|
+
que não existe levanta `ErroNaoEncontrado` (404). Um slug reservado, ou fora do
|
|
185
|
+
padrão `^[a-z0-9][a-z0-9_-]*$` com até 63 caracteres, levanta `ErroValidacao`
|
|
186
|
+
(422).
|
|
187
|
+
|
|
91
188
|
## Consultas no servidor
|
|
92
189
|
|
|
93
190
|
`consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
|
|
@@ -285,9 +382,9 @@ with ClienteDatamais(token=token_da_sessao) as cliente:
|
|
|
285
382
|
```
|
|
286
383
|
|
|
287
384
|
A autenticação é resolvida a cada requisição: o `token` vai como
|
|
288
|
-
`Authorization: Bearer` e, sem ele, vai o `X-API-Chave`.
|
|
289
|
-
|
|
290
|
-
sem token, antes de fazer a requisição.
|
|
385
|
+
`Authorization: Bearer` e, sem ele, vai o `X-API-Chave`. A única rota que só
|
|
386
|
+
aceita sessão, `acompanhar_dados_fonte_independente`, levanta
|
|
387
|
+
`ErroSessaoObrigatoria` sem token, antes de fazer a requisição.
|
|
291
388
|
|
|
292
389
|
`eu` devolve o `Usuario` da sessão, ou `None` quando ela não vale mais.
|
|
293
390
|
`eu(token)` usa outro token só naquela chamada. `sair` revoga a sessão na API
|
|
@@ -342,9 +439,9 @@ e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
|
|
|
342
439
|
cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
|
|
343
440
|
endereço final, por exemplo trocando `http://` por `https://`.
|
|
344
441
|
|
|
345
|
-
Cada `grupo` e `slug` entra na rota como um único segmento
|
|
346
|
-
`/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um
|
|
347
|
-
vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
|
|
442
|
+
Cada `grupo`, `colecao` e `slug` entra na rota como um único segmento
|
|
443
|
+
codificado, então `/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um
|
|
444
|
+
`grupo`, `colecao` ou `slug` vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
|
|
348
445
|
requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
|
|
349
446
|
nele, então a chamada poderia ir para outra rota com as suas credenciais. O
|
|
350
447
|
valor recusado fica em `segmento`.
|
|
@@ -30,6 +30,7 @@ from datamais_api.modelos import (
|
|
|
30
30
|
FalhaSincronizacao,
|
|
31
31
|
FiltroConsulta,
|
|
32
32
|
Fonte,
|
|
33
|
+
FonteGarantida,
|
|
33
34
|
FontePainel,
|
|
34
35
|
GradeWidgets,
|
|
35
36
|
GranularidadeConsulta,
|
|
@@ -52,7 +53,7 @@ from datamais_api.modelos import (
|
|
|
52
53
|
linhas_de_dataframe,
|
|
53
54
|
)
|
|
54
55
|
|
|
55
|
-
__version__ = "0.
|
|
56
|
+
__version__ = "0.7.0"
|
|
56
57
|
|
|
57
58
|
__all__ = [
|
|
58
59
|
"ACOES_FONTE_PADRAO",
|
|
@@ -60,6 +61,7 @@ __all__ = [
|
|
|
60
61
|
"PREFIXO_TIPO_PLUGIN",
|
|
61
62
|
"ErroAPI",
|
|
62
63
|
"Fonte",
|
|
64
|
+
"FonteGarantida",
|
|
63
65
|
"OperacaoAgregacao",
|
|
64
66
|
"ErroAutenticacao",
|
|
65
67
|
"Vinculo",
|
|
@@ -26,6 +26,7 @@ from datamais_api.modelos import (
|
|
|
26
26
|
DefinicaoPainel,
|
|
27
27
|
FalhaSincronizacao,
|
|
28
28
|
Fonte,
|
|
29
|
+
FonteGarantida,
|
|
29
30
|
Linha,
|
|
30
31
|
RelacaoFonte,
|
|
31
32
|
RelacaoPainel,
|
|
@@ -119,11 +120,7 @@ class ClienteDatamais:
|
|
|
119
120
|
def substituir_dados_fonte(
|
|
120
121
|
self, grupo: str, slug: str, colunas: list[Coluna], linhas: list[Linha]
|
|
121
122
|
) -> None:
|
|
122
|
-
|
|
123
|
-
"colunas": [coluna.para_payload() for coluna in colunas],
|
|
124
|
-
"linhas": linhas,
|
|
125
|
-
}
|
|
126
|
-
self._requisitar("PUT", _rota("/grupos/{}/fontes/{}/dados", grupo, slug), json=payload)
|
|
123
|
+
self._substituir_dados(_rota("/grupos/{}/fontes/{}/dados", grupo, slug), colunas, linhas)
|
|
127
124
|
|
|
128
125
|
def substituir_dados_fonte_de_dataframe(
|
|
129
126
|
self,
|
|
@@ -132,12 +129,24 @@ class ClienteDatamais:
|
|
|
132
129
|
frame: pd.DataFrame,
|
|
133
130
|
colunas: list[Coluna] | None = None,
|
|
134
131
|
) -> None:
|
|
135
|
-
self.substituir_dados_fonte(
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
)
|
|
132
|
+
self.substituir_dados_fonte(grupo, slug, *_conteudo_de_dataframe(frame, colunas))
|
|
133
|
+
|
|
134
|
+
def substituir_dados_fonte_independente(
|
|
135
|
+
self, slug: str, colunas: list[Coluna], linhas: list[Linha]
|
|
136
|
+
) -> None:
|
|
137
|
+
self._substituir_dados(_rota("/fontes/independentes/{}/dados", slug), colunas, linhas)
|
|
138
|
+
|
|
139
|
+
def substituir_dados_fonte_independente_de_dataframe(
|
|
140
|
+
self, slug: str, frame: pd.DataFrame, colunas: list[Coluna] | None = None
|
|
141
|
+
) -> None:
|
|
142
|
+
self.substituir_dados_fonte_independente(slug, *_conteudo_de_dataframe(frame, colunas))
|
|
143
|
+
|
|
144
|
+
def _substituir_dados(self, caminho: str, colunas: list[Coluna], linhas: list[Linha]) -> None:
|
|
145
|
+
payload: dict[str, Any] = {
|
|
146
|
+
"colunas": [coluna.para_payload() for coluna in colunas],
|
|
147
|
+
"linhas": linhas,
|
|
148
|
+
}
|
|
149
|
+
self._requisitar("PUT", caminho, json=payload)
|
|
141
150
|
|
|
142
151
|
def criar_fonte(
|
|
143
152
|
self,
|
|
@@ -157,6 +166,15 @@ class ClienteDatamais:
|
|
|
157
166
|
body = self._requisitar("POST", _rota("/grupos/{}/fontes", grupo), json=payload).json()
|
|
158
167
|
return Fonte.de_payload(body["fonte"])
|
|
159
168
|
|
|
169
|
+
def garantir_fonte_colecao(
|
|
170
|
+
self, colecao: str, slug: str, nome: str, *, descricao: str = ""
|
|
171
|
+
) -> FonteGarantida:
|
|
172
|
+
payload: dict[str, Any] = {"nome": nome}
|
|
173
|
+
if descricao:
|
|
174
|
+
payload["descricao"] = descricao
|
|
175
|
+
caminho = _rota("/colecoes/{}/fontes/{}", colecao, slug)
|
|
176
|
+
return FonteGarantida.de_payload(self._requisitar("PUT", caminho, json=payload).json())
|
|
177
|
+
|
|
160
178
|
def obter_relacoes_fonte(self, grupo: str, slug: str) -> list[RelacaoFonte]:
|
|
161
179
|
return self._obter_relacoes(_rota("/grupos/{}/fontes/{}/relacoes", grupo, slug))
|
|
162
180
|
|
|
@@ -168,15 +186,11 @@ class ClienteDatamais:
|
|
|
168
186
|
)
|
|
169
187
|
|
|
170
188
|
def obter_relacoes_fonte_independente(self, slug: str) -> list[RelacaoFonte]:
|
|
171
|
-
if not self._token:
|
|
172
|
-
raise ErroSessaoObrigatoria("Obter as relações de uma fonte independente")
|
|
173
189
|
return self._obter_relacoes(_rota("/fontes/independentes/{}/relacoes", slug))
|
|
174
190
|
|
|
175
191
|
def definir_relacoes_fonte_independente(
|
|
176
192
|
self, slug: str, relacoes: list[RelacaoFonte]
|
|
177
193
|
) -> list[RelacaoFonte]:
|
|
178
|
-
if not self._token:
|
|
179
|
-
raise ErroSessaoObrigatoria("Definir as relações de uma fonte independente")
|
|
180
194
|
return self._definir_relacoes(_rota("/fontes/independentes/{}/relacoes", slug), relacoes)
|
|
181
195
|
|
|
182
196
|
def _obter_relacoes(self, caminho: str) -> list[RelacaoFonte]:
|
|
@@ -340,5 +354,12 @@ def _rota(modelo: str, *segmentos: str) -> str:
|
|
|
340
354
|
return modelo.format(*(quote(segmento, safe="") for segmento in segmentos))
|
|
341
355
|
|
|
342
356
|
|
|
357
|
+
def _conteudo_de_dataframe(
|
|
358
|
+
frame: pd.DataFrame, colunas: list[Coluna] | None
|
|
359
|
+
) -> tuple[list[Coluna], list[Linha]]:
|
|
360
|
+
catalogo = colunas if colunas is not None else colunas_de_dataframe(frame)
|
|
361
|
+
return catalogo, linhas_de_dataframe(frame)
|
|
362
|
+
|
|
363
|
+
|
|
343
364
|
def _relacoes_de(body: dict[str, Any]) -> list[RelacaoFonte]:
|
|
344
365
|
return [RelacaoFonte.de_payload(relacao) for relacao in body.get("relacoes") or []]
|
|
@@ -87,6 +87,27 @@ class Fonte:
|
|
|
87
87
|
)
|
|
88
88
|
|
|
89
89
|
|
|
90
|
+
@dataclass(slots=True)
|
|
91
|
+
class FonteGarantida:
|
|
92
|
+
id: str
|
|
93
|
+
slug: str
|
|
94
|
+
nome: str
|
|
95
|
+
descricao: str
|
|
96
|
+
colecao: str
|
|
97
|
+
criada: bool
|
|
98
|
+
|
|
99
|
+
@classmethod
|
|
100
|
+
def de_payload(cls, payload: dict[str, Any]) -> "FonteGarantida":
|
|
101
|
+
return cls(
|
|
102
|
+
id=payload.get("id", ""),
|
|
103
|
+
slug=payload.get("slug", ""),
|
|
104
|
+
nome=payload.get("nome", ""),
|
|
105
|
+
descricao=payload.get("descricao", ""),
|
|
106
|
+
colecao=payload.get("colecao", ""),
|
|
107
|
+
criada=payload.get("criada", False),
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
|
|
90
111
|
@dataclass(slots=True)
|
|
91
112
|
class ColunaRelacao:
|
|
92
113
|
origem: str
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: datamais-api
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.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
|
|
@@ -107,6 +107,103 @@ existir e ter dono — uma chave não é um usuário, então ela nunca pode cria
|
|
|
107
107
|
grupo. Uma fonte que já existe volta como `ErroConflito`; um grupo inexistente
|
|
108
108
|
ou sem dono, como `ErroValidacao` (`422`).
|
|
109
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
|
+
|
|
169
|
+
## Fontes em coleções
|
|
170
|
+
|
|
171
|
+
Uma coleção reúne as fontes independentes que uma mesma carga alimenta. Uma
|
|
172
|
+
chave de API com `collection:<colecao>:manage` cria fontes independentes na
|
|
173
|
+
coleção e substitui os dados e as relações de todas elas, inclusive das criadas
|
|
174
|
+
depois da concessão. A carga não precisa de uma permissão nova para cada slug.
|
|
175
|
+
|
|
176
|
+
| Método | Rota | Credenciais |
|
|
177
|
+
| --- | --- | --- |
|
|
178
|
+
| `garantir_fonte_colecao(colecao, slug, nome, *, descricao="")` | `PUT /colecoes/{colecao}/fontes/{slug}` | chave de API ou sessão |
|
|
179
|
+
|
|
180
|
+
```python
|
|
181
|
+
from datamais_api import ClienteDatamais
|
|
182
|
+
|
|
183
|
+
with ClienteDatamais() as cliente:
|
|
184
|
+
fonte = cliente.garantir_fonte_colecao(
|
|
185
|
+
"programas", "propostas", "Propostas", descricao="Propostas de convênio"
|
|
186
|
+
)
|
|
187
|
+
cliente.substituir_dados_fonte_independente(fonte.slug, colunas, linhas)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
`garantir_fonte_colecao` é a chamada que uma carga faz antes de enviar os
|
|
191
|
+
dados, e devolve uma `FonteGarantida` (`id`, `slug`, `nome`, `descricao`,
|
|
192
|
+
`colecao`, `criada`). `criada` vale `True` quando a chamada criou a fonte (201)
|
|
193
|
+
e `False` quando ela já estava na coleção (200). Nesse segundo caso a fonte
|
|
194
|
+
fica com o nome e a descrição enviados: repetir a chamada com os mesmos valores
|
|
195
|
+
não muda nada, mas omitir `descricao` apaga a descrição que ela tinha. A fonte
|
|
196
|
+
criada herda o dono da coleção e só aparece para as pessoas depois que alguém a
|
|
197
|
+
anexa a um grupo.
|
|
198
|
+
|
|
199
|
+
Se o slug já pertence a uma fonte independente de outra coleção, ou de nenhuma,
|
|
200
|
+
a chamada levanta `ErroConflito` (409) com o lugar do slug no `detalhe`. Uma
|
|
201
|
+
chave sem `collection:<colecao>:manage` recebe `ErroProibido` (403). Com
|
|
202
|
+
sessão, que precisa de `datasets:independent`, `dev` ou `admin`, uma coleção
|
|
203
|
+
que não existe levanta `ErroNaoEncontrado` (404). Um slug reservado, ou fora do
|
|
204
|
+
padrão `^[a-z0-9][a-z0-9_-]*$` com até 63 caracteres, levanta `ErroValidacao`
|
|
205
|
+
(422).
|
|
206
|
+
|
|
110
207
|
## Consultas no servidor
|
|
111
208
|
|
|
112
209
|
`consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
|
|
@@ -304,9 +401,9 @@ with ClienteDatamais(token=token_da_sessao) as cliente:
|
|
|
304
401
|
```
|
|
305
402
|
|
|
306
403
|
A autenticação é resolvida a cada requisição: o `token` vai como
|
|
307
|
-
`Authorization: Bearer` e, sem ele, vai o `X-API-Chave`.
|
|
308
|
-
|
|
309
|
-
sem token, antes de fazer a requisição.
|
|
404
|
+
`Authorization: Bearer` e, sem ele, vai o `X-API-Chave`. A única rota que só
|
|
405
|
+
aceita sessão, `acompanhar_dados_fonte_independente`, levanta
|
|
406
|
+
`ErroSessaoObrigatoria` sem token, antes de fazer a requisição.
|
|
310
407
|
|
|
311
408
|
`eu` devolve o `Usuario` da sessão, ou `None` quando ela não vale mais.
|
|
312
409
|
`eu(token)` usa outro token só naquela chamada. `sair` revoga a sessão na API
|
|
@@ -361,9 +458,9 @@ e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
|
|
|
361
458
|
cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
|
|
362
459
|
endereço final, por exemplo trocando `http://` por `https://`.
|
|
363
460
|
|
|
364
|
-
Cada `grupo` e `slug` entra na rota como um único segmento
|
|
365
|
-
`/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um
|
|
366
|
-
vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
|
|
461
|
+
Cada `grupo`, `colecao` e `slug` entra na rota como um único segmento
|
|
462
|
+
codificado, então `/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um
|
|
463
|
+
`grupo`, `colecao` ou `slug` vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
|
|
367
464
|
requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
|
|
368
465
|
nele, então a chamada poderia ir para outra rota com as suas credenciais. O
|
|
369
466
|
valor recusado fica em `segmento`.
|
|
@@ -22,9 +22,9 @@ from datamais_api import (
|
|
|
22
22
|
ErroRedirecionamento,
|
|
23
23
|
ErroSegmentoInvalido,
|
|
24
24
|
ErroServicoIndisponivel,
|
|
25
|
-
ErroSessaoObrigatoria,
|
|
26
25
|
ErroValidacao,
|
|
27
26
|
FiltroConsulta,
|
|
27
|
+
FonteGarantida,
|
|
28
28
|
GranularidadeConsulta,
|
|
29
29
|
JuncaoConsulta,
|
|
30
30
|
OperacaoAgregacaoConsulta,
|
|
@@ -376,6 +376,38 @@ def test_substituir_dados_fonte_faz_put_do_conteudo_completo() -> None:
|
|
|
376
376
|
}
|
|
377
377
|
|
|
378
378
|
|
|
379
|
+
def test_substituir_dados_fonte_independente_faz_put_com_a_chave() -> None:
|
|
380
|
+
capturadas: list[httpx.Request] = []
|
|
381
|
+
|
|
382
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
383
|
+
capturadas.append(requisicao)
|
|
384
|
+
return httpx.Response(204)
|
|
385
|
+
|
|
386
|
+
colunas = [
|
|
387
|
+
Coluna("ibge", "IBGE", escondida=True),
|
|
388
|
+
Coluna("municipio", "Município", filtravel=True),
|
|
389
|
+
Coluna("populacao", "População", TipoColuna.INTEIRO),
|
|
390
|
+
]
|
|
391
|
+
linhas = [{"ibge": "1400100", "municipio": "Boa Vista", "populacao": 413486}]
|
|
392
|
+
|
|
393
|
+
with cliente_com(manipulador) as cliente:
|
|
394
|
+
cliente.substituir_dados_fonte_independente("municipios", colunas, linhas)
|
|
395
|
+
|
|
396
|
+
[requisicao] = capturadas
|
|
397
|
+
assert requisicao.method == "PUT"
|
|
398
|
+
assert str(requisicao.url) == f"{URL_BASE}/fontes/independentes/municipios/dados"
|
|
399
|
+
assert requisicao.headers["X-API-Chave"] == CHAVE_API
|
|
400
|
+
assert "Authorization" not in requisicao.headers
|
|
401
|
+
assert json.loads(requisicao.content) == {
|
|
402
|
+
"colunas": [
|
|
403
|
+
{"chave": "ibge", "cabecalho": "IBGE", "tipo": "text", "escondida": True},
|
|
404
|
+
{"chave": "municipio", "cabecalho": "Município", "tipo": "text", "filtravel": True},
|
|
405
|
+
{"chave": "populacao", "cabecalho": "População", "tipo": "int"},
|
|
406
|
+
],
|
|
407
|
+
"linhas": [{"ibge": "1400100", "municipio": "Boa Vista", "populacao": 413486}],
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
|
|
379
411
|
def test_criar_fonte_faz_post_da_entrada_de_catalogo() -> None:
|
|
380
412
|
capturado: dict[str, object] = {}
|
|
381
413
|
|
|
@@ -444,6 +476,104 @@ def test_criar_fonte_lanca_conflito_quando_ja_existe() -> None:
|
|
|
444
476
|
assert exc.value.status == 409
|
|
445
477
|
|
|
446
478
|
|
|
479
|
+
def test_garantir_fonte_colecao_cria_a_fonte_com_put_e_a_chave() -> None:
|
|
480
|
+
capturadas: list[httpx.Request] = []
|
|
481
|
+
|
|
482
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
483
|
+
capturadas.append(requisicao)
|
|
484
|
+
return httpx.Response(
|
|
485
|
+
201,
|
|
486
|
+
json={
|
|
487
|
+
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
488
|
+
"slug": "propostas",
|
|
489
|
+
"nome": "Propostas",
|
|
490
|
+
"descricao": "Propostas de convênio",
|
|
491
|
+
"colecao": "programas",
|
|
492
|
+
"criada": True,
|
|
493
|
+
},
|
|
494
|
+
)
|
|
495
|
+
|
|
496
|
+
with cliente_com(manipulador) as cliente:
|
|
497
|
+
fonte = cliente.garantir_fonte_colecao(
|
|
498
|
+
"programas", "propostas", "Propostas", descricao="Propostas de convênio"
|
|
499
|
+
)
|
|
500
|
+
|
|
501
|
+
[requisicao] = capturadas
|
|
502
|
+
assert requisicao.method == "PUT"
|
|
503
|
+
assert str(requisicao.url) == f"{URL_BASE}/colecoes/programas/fontes/propostas"
|
|
504
|
+
assert requisicao.headers["X-API-Chave"] == CHAVE_API
|
|
505
|
+
assert "Authorization" not in requisicao.headers
|
|
506
|
+
assert json.loads(requisicao.content) == {
|
|
507
|
+
"nome": "Propostas",
|
|
508
|
+
"descricao": "Propostas de convênio",
|
|
509
|
+
}
|
|
510
|
+
assert fonte == FonteGarantida(
|
|
511
|
+
id="550e8400-e29b-41d4-a716-446655440000",
|
|
512
|
+
slug="propostas",
|
|
513
|
+
nome="Propostas",
|
|
514
|
+
descricao="Propostas de convênio",
|
|
515
|
+
colecao="programas",
|
|
516
|
+
criada=True,
|
|
517
|
+
)
|
|
518
|
+
|
|
519
|
+
|
|
520
|
+
def test_garantir_fonte_colecao_omite_descricao_vazia_e_devolve_criada_falso() -> None:
|
|
521
|
+
capturado: dict[str, object] = {}
|
|
522
|
+
|
|
523
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
524
|
+
capturado["body"] = json.loads(requisicao.content)
|
|
525
|
+
return httpx.Response(
|
|
526
|
+
200,
|
|
527
|
+
json={
|
|
528
|
+
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
529
|
+
"slug": "propostas",
|
|
530
|
+
"nome": "Propostas",
|
|
531
|
+
"descricao": "",
|
|
532
|
+
"colecao": "programas",
|
|
533
|
+
"criada": False,
|
|
534
|
+
},
|
|
535
|
+
)
|
|
536
|
+
|
|
537
|
+
with cliente_com(manipulador) as cliente:
|
|
538
|
+
fonte = cliente.garantir_fonte_colecao("programas", "propostas", "Propostas")
|
|
539
|
+
|
|
540
|
+
assert capturado["body"] == {"nome": "Propostas"}
|
|
541
|
+
assert fonte.criada is False
|
|
542
|
+
assert fonte.colecao == "programas"
|
|
543
|
+
assert fonte.descricao == ""
|
|
544
|
+
|
|
545
|
+
|
|
546
|
+
@pytest.mark.parametrize(
|
|
547
|
+
("status", "tipo_erro", "detalhe"),
|
|
548
|
+
[
|
|
549
|
+
pytest.param(403, ErroProibido, "permissões insuficientes", id="sem_permissao"),
|
|
550
|
+
pytest.param(
|
|
551
|
+
409,
|
|
552
|
+
ErroConflito,
|
|
553
|
+
"já existe uma fonte independente com este slug na coleção outra",
|
|
554
|
+
id="slug_em_outra_colecao",
|
|
555
|
+
),
|
|
556
|
+
pytest.param(
|
|
557
|
+
409,
|
|
558
|
+
ErroConflito,
|
|
559
|
+
"já existe uma fonte independente com este slug fora de qualquer coleção",
|
|
560
|
+
id="slug_fora_de_colecao",
|
|
561
|
+
),
|
|
562
|
+
],
|
|
563
|
+
)
|
|
564
|
+
def test_garantir_fonte_colecao_mapeia_recusa_e_slug_ja_usado_fora_da_colecao(
|
|
565
|
+
status: int, tipo_erro: type[ErroAPI], detalhe: str
|
|
566
|
+
) -> None:
|
|
567
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
568
|
+
return httpx.Response(status, json={"status": status, "detail": detalhe})
|
|
569
|
+
|
|
570
|
+
with cliente_com(manipulador) as cliente, pytest.raises(tipo_erro) as exc:
|
|
571
|
+
cliente.garantir_fonte_colecao("programas", "propostas", "Propostas")
|
|
572
|
+
|
|
573
|
+
assert exc.value.status == status
|
|
574
|
+
assert exc.value.detalhe == detalhe
|
|
575
|
+
|
|
576
|
+
|
|
447
577
|
def test_obter_relacoes_fonte_analisa_o_payload() -> None:
|
|
448
578
|
visto: dict[str, str] = {}
|
|
449
579
|
|
|
@@ -549,15 +679,68 @@ def test_definir_relacoes_fonte_aceita_lista_vazia() -> None:
|
|
|
549
679
|
assert devolvidas == []
|
|
550
680
|
|
|
551
681
|
|
|
552
|
-
def
|
|
682
|
+
def test_obter_relacoes_fonte_independente_envia_a_chave_e_analisa_o_payload() -> None:
|
|
683
|
+
capturadas: list[httpx.Request] = []
|
|
684
|
+
|
|
553
685
|
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
554
|
-
|
|
686
|
+
capturadas.append(requisicao)
|
|
687
|
+
return httpx.Response(
|
|
688
|
+
200,
|
|
689
|
+
json={
|
|
690
|
+
"relacoes": [
|
|
691
|
+
{
|
|
692
|
+
"destino": {"fonte": "municipios", "independente": True},
|
|
693
|
+
"colunas": [{"origem": "ibge", "destino": "ibge"}],
|
|
694
|
+
"criado_em": "2026-11-04T10:00:00Z",
|
|
695
|
+
},
|
|
696
|
+
],
|
|
697
|
+
},
|
|
698
|
+
)
|
|
555
699
|
|
|
556
700
|
with cliente_com(manipulador) as cliente:
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
701
|
+
relacoes = cliente.obter_relacoes_fonte_independente("tabela-global")
|
|
702
|
+
|
|
703
|
+
[requisicao] = capturadas
|
|
704
|
+
assert requisicao.method == "GET"
|
|
705
|
+
assert str(requisicao.url) == f"{URL_BASE}/fontes/independentes/tabela-global/relacoes"
|
|
706
|
+
assert requisicao.headers["X-API-Chave"] == CHAVE_API
|
|
707
|
+
assert "Authorization" not in requisicao.headers
|
|
708
|
+
assert len(relacoes) == 1
|
|
709
|
+
assert relacoes[0].destino.fonte == "municipios"
|
|
710
|
+
assert relacoes[0].destino.independente is True
|
|
711
|
+
assert [(par.origem, par.destino) for par in relacoes[0].colunas] == [("ibge", "ibge")]
|
|
712
|
+
|
|
713
|
+
|
|
714
|
+
def test_definir_relacoes_fonte_independente_envia_a_chave_e_o_conjunto_completo() -> None:
|
|
715
|
+
capturadas: list[httpx.Request] = []
|
|
716
|
+
|
|
717
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
718
|
+
capturadas.append(requisicao)
|
|
719
|
+
return httpx.Response(200, json=json.loads(requisicao.content))
|
|
720
|
+
|
|
721
|
+
relacoes = [
|
|
722
|
+
RelacaoFonte(
|
|
723
|
+
destino=DestinoRelacao(fonte="municipios", independente=True),
|
|
724
|
+
colunas=[ColunaRelacao(origem="ibge", destino="ibge")],
|
|
725
|
+
),
|
|
726
|
+
]
|
|
727
|
+
|
|
728
|
+
with cliente_com(manipulador) as cliente:
|
|
729
|
+
devolvidas = cliente.definir_relacoes_fonte_independente("tabela-global", relacoes)
|
|
730
|
+
|
|
731
|
+
[requisicao] = capturadas
|
|
732
|
+
assert requisicao.method == "PUT"
|
|
733
|
+
assert str(requisicao.url) == f"{URL_BASE}/fontes/independentes/tabela-global/relacoes"
|
|
734
|
+
assert requisicao.headers["X-API-Chave"] == CHAVE_API
|
|
735
|
+
assert json.loads(requisicao.content) == {
|
|
736
|
+
"relacoes": [
|
|
737
|
+
{
|
|
738
|
+
"destino": {"fonte": "municipios", "independente": True},
|
|
739
|
+
"colunas": [{"origem": "ibge", "destino": "ibge"}],
|
|
740
|
+
},
|
|
741
|
+
],
|
|
742
|
+
}
|
|
743
|
+
assert [relacao.destino.fonte for relacao in devolvidas] == ["municipios"]
|
|
561
744
|
|
|
562
745
|
|
|
563
746
|
def test_definir_relacoes_fonte_independente_usa_o_token_da_sessao() -> None:
|
|
@@ -576,6 +759,42 @@ def test_definir_relacoes_fonte_independente_usa_o_token_da_sessao() -> None:
|
|
|
576
759
|
assert capturado["autorizacao"] == "Bearer tok-1"
|
|
577
760
|
|
|
578
761
|
|
|
762
|
+
@pytest.mark.parametrize(
|
|
763
|
+
("status", "tipo_erro"),
|
|
764
|
+
[(403, ErroProibido), (404, ErroNaoEncontrado)],
|
|
765
|
+
)
|
|
766
|
+
@pytest.mark.parametrize(
|
|
767
|
+
"chamada",
|
|
768
|
+
[
|
|
769
|
+
pytest.param(
|
|
770
|
+
lambda c: c.substituir_dados_fonte_independente(
|
|
771
|
+
"tabela-global", [Coluna("uf", "UF")], [{"uf": "RR"}]
|
|
772
|
+
),
|
|
773
|
+
id="substituir_dados_fonte_independente",
|
|
774
|
+
),
|
|
775
|
+
pytest.param(
|
|
776
|
+
lambda c: c.obter_relacoes_fonte_independente("tabela-global"),
|
|
777
|
+
id="obter_relacoes_fonte_independente",
|
|
778
|
+
),
|
|
779
|
+
pytest.param(
|
|
780
|
+
lambda c: c.definir_relacoes_fonte_independente("tabela-global", []),
|
|
781
|
+
id="definir_relacoes_fonte_independente",
|
|
782
|
+
),
|
|
783
|
+
],
|
|
784
|
+
)
|
|
785
|
+
def test_escrita_de_fonte_independente_por_chave_mapeia_recusa_e_ausencia(
|
|
786
|
+
chamada: Callable[[ClienteDatamais], object], status: int, tipo_erro: type[ErroAPI]
|
|
787
|
+
) -> None:
|
|
788
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
789
|
+
return httpx.Response(status, json={"status": status, "detail": "sem acesso à fonte"})
|
|
790
|
+
|
|
791
|
+
with cliente_com(manipulador) as cliente, pytest.raises(tipo_erro) as exc:
|
|
792
|
+
chamada(cliente)
|
|
793
|
+
|
|
794
|
+
assert exc.value.status == status
|
|
795
|
+
assert exc.value.detalhe == "sem acesso à fonte"
|
|
796
|
+
|
|
797
|
+
|
|
579
798
|
@pytest.mark.parametrize(
|
|
580
799
|
("status", "tipo_erro"),
|
|
581
800
|
[
|
|
@@ -753,11 +972,21 @@ def test_slug_vai_na_rota_como_um_unico_segmento_codificado(slug: str, segmento:
|
|
|
753
972
|
"/grupos/..%2Fg/fontes/a%2Fb/dados",
|
|
754
973
|
id="substituir_dados_fonte",
|
|
755
974
|
),
|
|
975
|
+
pytest.param(
|
|
976
|
+
lambda c: c.substituir_dados_fonte_independente("a/b", [], []),
|
|
977
|
+
"/fontes/independentes/a%2Fb/dados",
|
|
978
|
+
id="substituir_dados_fonte_independente",
|
|
979
|
+
),
|
|
756
980
|
pytest.param(
|
|
757
981
|
lambda c: c.criar_fonte("../g", "a/b", "Programas"),
|
|
758
982
|
"/grupos/..%2Fg/fontes",
|
|
759
983
|
id="criar_fonte",
|
|
760
984
|
),
|
|
985
|
+
pytest.param(
|
|
986
|
+
lambda c: c.garantir_fonte_colecao("../c", "a/b", "Propostas"),
|
|
987
|
+
"/colecoes/..%2Fc/fontes/a%2Fb",
|
|
988
|
+
id="garantir_fonte_colecao",
|
|
989
|
+
),
|
|
761
990
|
pytest.param(
|
|
762
991
|
lambda c: c.obter_relacoes_fonte("../g", "a/b"),
|
|
763
992
|
"/grupos/..%2Fg/fontes/a%2Fb/relacoes",
|
|
@@ -844,11 +1073,14 @@ def test_segmento_vazio_ou_de_ponto_levanta_erro_antes_de_qualquer_requisicao(
|
|
|
844
1073
|
cliente.substituir_dados_fonte("geral", segmento, [], [])
|
|
845
1074
|
with pytest.raises(ErroSegmentoInvalido) as no_fluxo:
|
|
846
1075
|
cliente.acompanhar_dados_painel("geral", segmento)
|
|
1076
|
+
with pytest.raises(ErroSegmentoInvalido) as no_independente:
|
|
1077
|
+
cliente.substituir_dados_fonte_independente(segmento, [], [])
|
|
847
1078
|
|
|
848
1079
|
assert capturadas == []
|
|
849
1080
|
assert no_grupo.value.segmento == segmento
|
|
850
1081
|
assert no_slug.value.segmento == segmento
|
|
851
1082
|
assert no_fluxo.value.segmento == segmento
|
|
1083
|
+
assert no_independente.value.segmento == segmento
|
|
852
1084
|
assert str(no_grupo.value) == (
|
|
853
1085
|
f"segmento de rota inválido: {segmento!r}; "
|
|
854
1086
|
"grupo e slug não podem ser vazios nem iguais a '.' ou '..'"
|
|
@@ -128,3 +128,30 @@ def test_substituir_dados_fonte_de_dataframe_respeita_colunas_explicitas() -> No
|
|
|
128
128
|
],
|
|
129
129
|
"linhas": [{"valor": 10.0}],
|
|
130
130
|
}
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def test_substituir_dados_fonte_independente_de_dataframe_envia_para_o_slug_global() -> None:
|
|
134
|
+
capturadas: list[httpx.Request] = []
|
|
135
|
+
|
|
136
|
+
def manipulador(requisicao: httpx.Request) -> httpx.Response:
|
|
137
|
+
capturadas.append(requisicao)
|
|
138
|
+
return httpx.Response(204)
|
|
139
|
+
|
|
140
|
+
frame = pd.DataFrame({"ibge": ["1400100"], "populacao": [413486]})
|
|
141
|
+
cliente = ClienteDatamais(
|
|
142
|
+
"https://api.example.com", "dmk_secret", transport=httpx.MockTransport(manipulador)
|
|
143
|
+
)
|
|
144
|
+
|
|
145
|
+
with cliente:
|
|
146
|
+
cliente.substituir_dados_fonte_independente_de_dataframe("municipios", frame)
|
|
147
|
+
|
|
148
|
+
[requisicao] = capturadas
|
|
149
|
+
assert requisicao.method == "PUT"
|
|
150
|
+
assert str(requisicao.url) == "https://api.example.com/fontes/independentes/municipios/dados"
|
|
151
|
+
assert json.loads(requisicao.content) == {
|
|
152
|
+
"colunas": [
|
|
153
|
+
{"chave": "ibge", "cabecalho": "ibge", "tipo": "text"},
|
|
154
|
+
{"chave": "populacao", "cabecalho": "populacao", "tipo": "int"},
|
|
155
|
+
],
|
|
156
|
+
"linhas": [{"ibge": "1400100", "populacao": 413486}],
|
|
157
|
+
}
|
|
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
|
|
File without changes
|