datamais-api 0.6.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.6.0/src/datamais_api.egg-info → datamais_api-0.7.0}/PKG-INFO +42 -4
  2. {datamais_api-0.6.0 → datamais_api-0.7.0}/README.md +41 -3
  3. {datamais_api-0.6.0 → datamais_api-0.7.0}/pyproject.toml +1 -1
  4. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api/__init__.py +3 -1
  5. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api/cliente.py +10 -0
  6. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api/modelos.py +21 -0
  7. {datamais_api-0.6.0 → datamais_api-0.7.0/src/datamais_api.egg-info}/PKG-INFO +42 -4
  8. {datamais_api-0.6.0 → datamais_api-0.7.0}/tests/test_cliente.py +104 -0
  9. {datamais_api-0.6.0 → datamais_api-0.7.0}/LICENSE +0 -0
  10. {datamais_api-0.6.0 → datamais_api-0.7.0}/setup.cfg +0 -0
  11. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api/config.py +0 -0
  12. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api/erros.py +0 -0
  13. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api/eventos.py +0 -0
  14. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api/py.typed +0 -0
  15. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/SOURCES.txt +0 -0
  16. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/dependency_links.txt +0 -0
  17. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/requires.txt +0 -0
  18. {datamais_api-0.6.0 → datamais_api-0.7.0}/src/datamais_api.egg-info/top_level.txt +0 -0
  19. {datamais_api-0.6.0 → datamais_api-0.7.0}/tests/test_acompanhar.py +0 -0
  20. {datamais_api-0.6.0 → datamais_api-0.7.0}/tests/test_config.py +0 -0
  21. {datamais_api-0.6.0 → datamais_api-0.7.0}/tests/test_eventos.py +0 -0
  22. {datamais_api-0.6.0 → datamais_api-0.7.0}/tests/test_layout.py +0 -0
  23. {datamais_api-0.6.0 → datamais_api-0.7.0}/tests/test_pandas.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: datamais-api
3
- Version: 0.6.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
@@ -166,6 +166,44 @@ são os mesmos de `obter_relacoes_fonte` e `definir_relacoes_fonte`.
166
166
  Uma chave sem a permissão da fonte recebe `ErroProibido` (403), e um slug que
167
167
  não existe, `ErroNaoEncontrado` (404).
168
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
+
169
207
  ## Consultas no servidor
170
208
 
171
209
  `consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
@@ -420,9 +458,9 @@ e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
420
458
  cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
421
459
  endereço final, por exemplo trocando `http://` por `https://`.
422
460
 
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
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
426
464
  requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
427
465
  nele, então a chamada poderia ir para outra rota com as suas credenciais. O
428
466
  valor recusado fica em `segmento`.
@@ -147,6 +147,44 @@ são os mesmos de `obter_relacoes_fonte` e `definir_relacoes_fonte`.
147
147
  Uma chave sem a permissão da fonte recebe `ErroProibido` (403), e um slug que
148
148
  não existe, `ErroNaoEncontrado` (404).
149
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
+
150
188
  ## Consultas no servidor
151
189
 
152
190
  `consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
@@ -401,9 +439,9 @@ e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
401
439
  cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
402
440
  endereço final, por exemplo trocando `http://` por `https://`.
403
441
 
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
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
407
445
  requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
408
446
  nele, então a chamada poderia ir para outra rota com as suas credenciais. O
409
447
  valor recusado fica em `segmento`.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "datamais-api"
3
- version = "0.6.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.6.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,
@@ -165,6 +166,15 @@ class ClienteDatamais:
165
166
  body = self._requisitar("POST", _rota("/grupos/{}/fontes", grupo), json=payload).json()
166
167
  return Fonte.de_payload(body["fonte"])
167
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
+
168
178
  def obter_relacoes_fonte(self, grupo: str, slug: str) -> list[RelacaoFonte]:
169
179
  return self._obter_relacoes(_rota("/grupos/{}/fontes/{}/relacoes", grupo, slug))
170
180
 
@@ -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.6.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
@@ -166,6 +166,44 @@ são os mesmos de `obter_relacoes_fonte` e `definir_relacoes_fonte`.
166
166
  Uma chave sem a permissão da fonte recebe `ErroProibido` (403), e um slug que
167
167
  não existe, `ErroNaoEncontrado` (404).
168
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
+
169
207
  ## Consultas no servidor
170
208
 
171
209
  `consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
@@ -420,9 +458,9 @@ e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
420
458
  cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
421
459
  endereço final, por exemplo trocando `http://` por `https://`.
422
460
 
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
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
426
464
  requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
427
465
  nele, então a chamada poderia ir para outra rota com as suas credenciais. O
428
466
  valor recusado fica em `segmento`.
@@ -24,6 +24,7 @@ from datamais_api import (
24
24
  ErroServicoIndisponivel,
25
25
  ErroValidacao,
26
26
  FiltroConsulta,
27
+ FonteGarantida,
27
28
  GranularidadeConsulta,
28
29
  JuncaoConsulta,
29
30
  OperacaoAgregacaoConsulta,
@@ -475,6 +476,104 @@ def test_criar_fonte_lanca_conflito_quando_ja_existe() -> None:
475
476
  assert exc.value.status == 409
476
477
 
477
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
+
478
577
  def test_obter_relacoes_fonte_analisa_o_payload() -> None:
479
578
  visto: dict[str, str] = {}
480
579
 
@@ -883,6 +982,11 @@ def test_slug_vai_na_rota_como_um_unico_segmento_codificado(slug: str, segmento:
883
982
  "/grupos/..%2Fg/fontes",
884
983
  id="criar_fonte",
885
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
+ ),
886
990
  pytest.param(
887
991
  lambda c: c.obter_relacoes_fonte("../g", "a/b"),
888
992
  "/grupos/..%2Fg/fontes/a%2Fb/relacoes",
File without changes
File without changes