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.
Files changed (23) hide show
  1. {datamais_api-0.5.0/src/datamais_api.egg-info → datamais_api-0.7.0}/PKG-INFO +104 -7
  2. {datamais_api-0.5.0 → datamais_api-0.7.0}/README.md +103 -6
  3. {datamais_api-0.5.0 → datamais_api-0.7.0}/pyproject.toml +1 -1
  4. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/__init__.py +3 -1
  5. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/cliente.py +36 -15
  6. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/modelos.py +21 -0
  7. {datamais_api-0.5.0 → datamais_api-0.7.0/src/datamais_api.egg-info}/PKG-INFO +104 -7
  8. {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_cliente.py +239 -7
  9. {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_pandas.py +27 -0
  10. {datamais_api-0.5.0 → datamais_api-0.7.0}/LICENSE +0 -0
  11. {datamais_api-0.5.0 → datamais_api-0.7.0}/setup.cfg +0 -0
  12. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/config.py +0 -0
  13. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/erros.py +0 -0
  14. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/eventos.py +0 -0
  15. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api/py.typed +0 -0
  16. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/SOURCES.txt +0 -0
  17. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/dependency_links.txt +0 -0
  18. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/requires.txt +0 -0
  19. {datamais_api-0.5.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/top_level.txt +0 -0
  20. {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_acompanhar.py +0 -0
  21. {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_config.py +0 -0
  22. {datamais_api-0.5.0 → datamais_api-0.7.0}/tests/test_eventos.py +0 -0
  23. {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.5.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`. As rotas que só
308
- aceitam sessão (as de fontes independentes) levantam `ErroSessaoObrigatoria`
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 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
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`. As rotas que só
289
- aceitam sessão (as de fontes independentes) levantam `ErroSessaoObrigatoria`
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 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
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`.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "datamais-api"
3
- version = "0.5.0"
3
+ version = "0.7.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"
@@ -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.5.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
- payload: dict[str, Any] = {
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
- grupo,
137
- slug,
138
- colunas if colunas is not None else colunas_de_dataframe(frame),
139
- linhas_de_dataframe(frame),
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.5.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`. As rotas que só
308
- aceitam sessão (as de fontes independentes) levantam `ErroSessaoObrigatoria`
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 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
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 test_relacoes_de_fonte_independente_exigem_sessao() -> None:
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
- raise AssertionError("não deveria chegar à rede sem sessão")
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
- with pytest.raises(ErroSessaoObrigatoria):
558
- cliente.obter_relacoes_fonte_independente("tabela-global")
559
- with pytest.raises(ErroSessaoObrigatoria):
560
- cliente.definir_relacoes_fonte_independente("tabela-global", [])
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