datamais-api 0.3.0__py3-none-any.whl

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.
@@ -0,0 +1,81 @@
1
+ from datamais_api.cliente import ACOES_FONTE_PADRAO, ClienteDatamais
2
+ from datamais_api.config import Configuracoes
3
+ from datamais_api.erros import (
4
+ ErroAPI,
5
+ ErroAutenticacao,
6
+ ErroConfigAusente,
7
+ ErroConflito,
8
+ ErroDatamais,
9
+ ErroNaoEncontrado,
10
+ ErroProibido,
11
+ ErroSessaoObrigatoria,
12
+ ErroValidacao,
13
+ )
14
+ from datamais_api.modelos import (
15
+ PREFIXO_TIPO_PLUGIN,
16
+ TIPOS_WIDGET_NATIVOS,
17
+ Aba,
18
+ Coluna,
19
+ ColunaRelacao,
20
+ DadosPainel,
21
+ DefinicaoPainel,
22
+ DestinoRelacao,
23
+ Fonte,
24
+ FontePainel,
25
+ GradeWidgets,
26
+ Linha,
27
+ OperacaoAgregacao,
28
+ PosicaoWidget,
29
+ RelacaoFonte,
30
+ ResultadoLogin,
31
+ TipoColuna,
32
+ TipoWidget,
33
+ TipoWidgetNativo,
34
+ Usuario,
35
+ Vinculo,
36
+ Widget,
37
+ colunas_de_dataframe,
38
+ linhas_de_dataframe,
39
+ )
40
+
41
+ __version__ = "0.3.0"
42
+
43
+ __all__ = [
44
+ "ACOES_FONTE_PADRAO",
45
+ "TIPOS_WIDGET_NATIVOS",
46
+ "PREFIXO_TIPO_PLUGIN",
47
+ "ErroAPI",
48
+ "Fonte",
49
+ "OperacaoAgregacao",
50
+ "ErroAutenticacao",
51
+ "Vinculo",
52
+ "TipoWidgetNativo",
53
+ "Coluna",
54
+ "ColunaRelacao",
55
+ "DestinoRelacao",
56
+ "RelacaoFonte",
57
+ "TipoColuna",
58
+ "ErroConflito",
59
+ "ClienteDatamais",
60
+ "ErroDatamais",
61
+ "ErroProibido",
62
+ "ResultadoLogin",
63
+ "ErroConfigAusente",
64
+ "ErroNaoEncontrado",
65
+ "DadosPainel",
66
+ "DefinicaoPainel",
67
+ "FontePainel",
68
+ "Linha",
69
+ "ErroSessaoObrigatoria",
70
+ "Configuracoes",
71
+ "Aba",
72
+ "Usuario",
73
+ "ErroValidacao",
74
+ "Widget",
75
+ "GradeWidgets",
76
+ "PosicaoWidget",
77
+ "TipoWidget",
78
+ "__version__",
79
+ "colunas_de_dataframe",
80
+ "linhas_de_dataframe",
81
+ ]
@@ -0,0 +1,221 @@
1
+ from datetime import datetime
2
+ from types import TracebackType
3
+ from typing import Any
4
+
5
+ import httpx
6
+ import pandas as pd
7
+
8
+ from datamais_api.config import resolver
9
+ from datamais_api.erros import (
10
+ ErroAutenticacao,
11
+ ErroDatamais,
12
+ ErroNaoEncontrado,
13
+ ErroSessaoObrigatoria,
14
+ de_resposta,
15
+ )
16
+ from datamais_api.modelos import (
17
+ Coluna,
18
+ DadosPainel,
19
+ DefinicaoPainel,
20
+ Fonte,
21
+ Linha,
22
+ RelacaoFonte,
23
+ ResultadoLogin,
24
+ Usuario,
25
+ colunas_de_dataframe,
26
+ linhas_de_dataframe,
27
+ )
28
+
29
+ ACOES_FONTE_PADRAO = ("view", "manage")
30
+
31
+
32
+ class ClienteDatamais:
33
+ def __init__(
34
+ self,
35
+ url_base: str | None = None,
36
+ chave_api: str | None = None,
37
+ token: str | None = None,
38
+ timeout: float = 30.0,
39
+ transport: httpx.BaseTransport | None = None,
40
+ ) -> None:
41
+ config = resolver(url_base, chave_api, token)
42
+ self._chave_api = config.chave_api
43
+ self._token = config.token
44
+ self._http = httpx.Client(
45
+ base_url=config.url_base,
46
+ timeout=timeout,
47
+ transport=transport,
48
+ )
49
+
50
+ @property
51
+ def token(self) -> str | None:
52
+ return self._token
53
+
54
+ def obter_dados_fonte(self, grupo: str, slug: str) -> DadosPainel:
55
+ body = self._requisitar("GET", f"/v1/grupos/{grupo}/fontes/{slug}/dados").json()
56
+ atualizado_em = body.get("atualizado_em")
57
+ return DadosPainel(
58
+ colunas=[Coluna.de_payload(coluna) for coluna in body["colunas"]],
59
+ linhas=body.get("linhas") or [],
60
+ atualizado_em=datetime.fromisoformat(atualizado_em) if atualizado_em else None,
61
+ )
62
+
63
+ def substituir_dados_fonte(
64
+ self, grupo: str, slug: str, colunas: list[Coluna], linhas: list[Linha]
65
+ ) -> None:
66
+ payload: dict[str, Any] = {
67
+ "colunas": [coluna.para_payload() for coluna in colunas],
68
+ "linhas": linhas,
69
+ }
70
+ self._requisitar("PUT", f"/v1/grupos/{grupo}/fontes/{slug}/dados", json=payload)
71
+
72
+ def substituir_dados_fonte_de_dataframe(
73
+ self,
74
+ grupo: str,
75
+ slug: str,
76
+ frame: pd.DataFrame,
77
+ colunas: list[Coluna] | None = None,
78
+ ) -> None:
79
+ self.substituir_dados_fonte(
80
+ grupo,
81
+ slug,
82
+ colunas if colunas is not None else colunas_de_dataframe(frame),
83
+ linhas_de_dataframe(frame),
84
+ )
85
+
86
+ def criar_fonte(
87
+ self,
88
+ grupo: str,
89
+ slug: str,
90
+ nome: str,
91
+ acoes: list[str] | None = None,
92
+ descricao: str = "",
93
+ ) -> Fonte:
94
+ payload: dict[str, Any] = {
95
+ "slug": slug,
96
+ "nome": nome,
97
+ "acoes": acoes if acoes else list(ACOES_FONTE_PADRAO),
98
+ }
99
+ if descricao:
100
+ payload["descricao"] = descricao
101
+ body = self._requisitar("POST", f"/v1/grupos/{grupo}/fontes", json=payload).json()
102
+ return Fonte.de_payload(body["fonte"])
103
+
104
+ def obter_relacoes_fonte(self, grupo: str, slug: str) -> list[RelacaoFonte]:
105
+ return self._obter_relacoes(f"/v1/grupos/{grupo}/fontes/{slug}/relacoes")
106
+
107
+ def definir_relacoes_fonte(
108
+ self, grupo: str, slug: str, relacoes: list[RelacaoFonte]
109
+ ) -> list[RelacaoFonte]:
110
+ return self._definir_relacoes(f"/v1/grupos/{grupo}/fontes/{slug}/relacoes", relacoes)
111
+
112
+ def obter_relacoes_fonte_independente(self, slug: str) -> list[RelacaoFonte]:
113
+ if not self._token:
114
+ raise ErroSessaoObrigatoria("Obter as relações de uma fonte independente")
115
+ return self._obter_relacoes(f"/v1/fontes/independentes/{slug}/relacoes")
116
+
117
+ def definir_relacoes_fonte_independente(
118
+ self, slug: str, relacoes: list[RelacaoFonte]
119
+ ) -> list[RelacaoFonte]:
120
+ if not self._token:
121
+ raise ErroSessaoObrigatoria("Definir as relações de uma fonte independente")
122
+ return self._definir_relacoes(f"/v1/fontes/independentes/{slug}/relacoes", relacoes)
123
+
124
+ def _obter_relacoes(self, caminho: str) -> list[RelacaoFonte]:
125
+ body = self._requisitar("GET", caminho).json()
126
+ return _relacoes_de(body)
127
+
128
+ def _definir_relacoes(self, caminho: str, relacoes: list[RelacaoFonte]) -> list[RelacaoFonte]:
129
+ payload = {"relacoes": [relacao.para_payload() for relacao in relacoes]}
130
+ body = self._requisitar("PUT", caminho, json=payload).json()
131
+ return _relacoes_de(body)
132
+
133
+ def obter_layout(self, grupo: str, slug: str) -> DefinicaoPainel | None:
134
+ try:
135
+ body = self._requisitar("GET", f"/v1/grupos/{grupo}/paineis/{slug}/layout").json()
136
+ except ErroNaoEncontrado:
137
+ return None
138
+ return DefinicaoPainel.de_payload(body)
139
+
140
+ def substituir_layout(self, grupo: str, slug: str, definicao: DefinicaoPainel) -> None:
141
+ if not self._token:
142
+ raise ErroSessaoObrigatoria("Substituir o layout de um painel")
143
+ self._requisitar(
144
+ "PUT",
145
+ f"/v1/grupos/{grupo}/paineis/{slug}/layout",
146
+ json=definicao.para_payload(),
147
+ )
148
+
149
+ def entrar(
150
+ self, email: str, senha: str, chave_permissao: str | None = None
151
+ ) -> ResultadoLogin | None:
152
+ payload: dict[str, Any] = {"email": email, "senha": senha}
153
+ if chave_permissao:
154
+ payload["chave_permissao"] = chave_permissao
155
+ try:
156
+ body = self._requisitar(
157
+ "POST", "/v1/auth/entrar", autenticar=False, json=payload
158
+ ).json()
159
+ except ErroAutenticacao:
160
+ return None
161
+ self._token = body["token"]["token_acesso"]
162
+ return ResultadoLogin(token=self._token, usuario=Usuario.de_payload(body["usuario"]))
163
+
164
+ def eu(self, token: str | None = None) -> Usuario | None:
165
+ try:
166
+ body = self._requisitar("GET", "/v1/auth/eu", token=token).json()
167
+ except ErroAutenticacao:
168
+ return None
169
+ return Usuario.de_payload(body)
170
+
171
+ def sair(self) -> None:
172
+ try:
173
+ self._requisitar("POST", "/v1/auth/sair")
174
+ except ErroDatamais:
175
+ pass
176
+ self._token = None
177
+
178
+ def fechar(self) -> None:
179
+ self._http.close()
180
+
181
+ def __enter__(self) -> "ClienteDatamais":
182
+ return self
183
+
184
+ def __exit__(
185
+ self,
186
+ exc_type: type[BaseException] | None,
187
+ exc: BaseException | None,
188
+ tb: TracebackType | None,
189
+ ) -> None:
190
+ self.fechar()
191
+
192
+ def _cabecalhos_auth(self, token: str | None, autenticar: bool) -> dict[str, str]:
193
+ if token:
194
+ return {"Authorization": f"Bearer {token}"}
195
+ if not autenticar:
196
+ return {}
197
+ if self._token:
198
+ return {"Authorization": f"Bearer {self._token}"}
199
+ if self._chave_api:
200
+ return {"X-API-Chave": self._chave_api}
201
+ return {}
202
+
203
+ def _requisitar(
204
+ self,
205
+ method: str,
206
+ path: str,
207
+ *,
208
+ token: str | None = None,
209
+ autenticar: bool = True,
210
+ **kwargs: Any,
211
+ ) -> httpx.Response:
212
+ cabecalhos: dict[str, str] = dict(kwargs.pop("headers", None) or {})
213
+ cabecalhos.update(self._cabecalhos_auth(token, autenticar))
214
+ resposta = self._http.request(method, path, headers=cabecalhos, **kwargs)
215
+ if resposta.is_error:
216
+ raise de_resposta(resposta)
217
+ return resposta
218
+
219
+
220
+ def _relacoes_de(body: dict[str, Any]) -> list[RelacaoFonte]:
221
+ return [RelacaoFonte.de_payload(relacao) for relacao in body.get("relacoes") or []]
datamais_api/config.py ADDED
@@ -0,0 +1,28 @@
1
+ import os
2
+ from dataclasses import dataclass
3
+
4
+ from datamais_api.erros import ErroConfigAusente
5
+
6
+ ENV_URL_BASE = "DATAMAIS_BASE_URL"
7
+ ENV_CHAVE_API = "DATAMAIS_API_KEY"
8
+
9
+
10
+ @dataclass(frozen=True, slots=True)
11
+ class Configuracoes:
12
+ url_base: str
13
+ chave_api: str | None = None
14
+ token: str | None = None
15
+
16
+
17
+ def resolver(
18
+ url_base: str | None = None,
19
+ chave_api: str | None = None,
20
+ token: str | None = None,
21
+ ) -> Configuracoes:
22
+ url_resolvida = url_base or os.environ.get(ENV_URL_BASE, "")
23
+ chave_resolvida = chave_api or os.environ.get(ENV_CHAVE_API) or None
24
+ if not url_resolvida:
25
+ raise ErroConfigAusente(ENV_URL_BASE)
26
+ return Configuracoes(
27
+ url_base=url_resolvida.rstrip("/"), chave_api=chave_resolvida, token=token
28
+ )
datamais_api/erros.py ADDED
@@ -0,0 +1,72 @@
1
+ from typing import Any
2
+
3
+ import httpx
4
+
5
+
6
+ class ErroDatamais(Exception):
7
+ pass
8
+
9
+
10
+ class ErroConfigAusente(ErroDatamais):
11
+ def __init__(self, var_ambiente: str) -> None:
12
+ super().__init__(
13
+ f"{var_ambiente} não está definida; exporte-a ou passe o valor a ClienteDatamais"
14
+ )
15
+ self.var_ambiente = var_ambiente
16
+
17
+
18
+ class ErroSessaoObrigatoria(ErroDatamais):
19
+ def __init__(self, acao: str) -> None:
20
+ super().__init__(f"{acao} exige uma sessão de usuário; chame entrar() primeiro")
21
+ self.acao = acao
22
+
23
+
24
+ class ErroAPI(ErroDatamais):
25
+ def __init__(self, status: int, detalhe: str, erros: list[dict[str, Any]]) -> None:
26
+ super().__init__(f"HTTP {status}: {detalhe}")
27
+ self.status = status
28
+ self.detalhe = detalhe
29
+ self.erros = erros
30
+
31
+
32
+ class ErroAutenticacao(ErroAPI): ...
33
+
34
+
35
+ class ErroProibido(ErroAPI): ...
36
+
37
+
38
+ class ErroNaoEncontrado(ErroAPI): ...
39
+
40
+
41
+ class ErroConflito(ErroAPI): ...
42
+
43
+
44
+ class ErroValidacao(ErroAPI): ...
45
+
46
+
47
+ _ERROS_POR_STATUS: dict[int, type[ErroAPI]] = {
48
+ 401: ErroAutenticacao,
49
+ 403: ErroProibido,
50
+ 404: ErroNaoEncontrado,
51
+ 409: ErroConflito,
52
+ 422: ErroValidacao,
53
+ }
54
+
55
+
56
+ def de_resposta(resposta: httpx.Response) -> ErroAPI:
57
+ detalhe, lista_erros = _detalhes_problema(resposta)
58
+ tipo_erro = _ERROS_POR_STATUS.get(resposta.status_code, ErroAPI)
59
+ return tipo_erro(resposta.status_code, detalhe, lista_erros)
60
+
61
+
62
+ def _detalhes_problema(resposta: httpx.Response) -> tuple[str, list[dict[str, Any]]]:
63
+ reserva = resposta.reason_phrase or "erro inesperado da api"
64
+ try:
65
+ body = resposta.json()
66
+ except ValueError:
67
+ return reserva, []
68
+ if not isinstance(body, dict):
69
+ return reserva, []
70
+ detalhe = body.get("detail") or body.get("title") or reserva
71
+ lista_erros = body.get("errors")
72
+ return str(detalhe), lista_erros if isinstance(lista_erros, list) else []
@@ -0,0 +1,426 @@
1
+ import math
2
+ from collections.abc import Callable
3
+ from dataclasses import dataclass, field
4
+ from datetime import datetime
5
+ from enum import StrEnum
6
+ from typing import Any
7
+
8
+ import numpy as np
9
+ import pandas as pd
10
+ from pandas.api import types as pdtypes
11
+
12
+ Linha = dict[str, Any]
13
+
14
+
15
+ class TipoColuna(StrEnum):
16
+ TEXTO = "text"
17
+ INTEIRO = "int"
18
+ NUMERO = "number"
19
+ DINHEIRO = "money"
20
+ DATA = "date"
21
+ DATA_HORA = "datetime"
22
+ PERCENTUAL = "percent"
23
+ DIAS = "days"
24
+ VINCULO = "link"
25
+ BOOLEANO = "bool"
26
+
27
+
28
+ @dataclass(slots=True)
29
+ class Coluna:
30
+ chave: str
31
+ cabecalho: str
32
+ tipo: TipoColuna | str = TipoColuna.TEXTO
33
+ filtravel: bool = False
34
+ variante_filtro: str | None = None
35
+
36
+ def para_payload(self) -> dict[str, Any]:
37
+ payload: dict[str, Any] = {
38
+ "chave": self.chave,
39
+ "cabecalho": self.cabecalho,
40
+ "tipo": str(self.tipo),
41
+ }
42
+ if self.filtravel:
43
+ payload["filtravel"] = True
44
+ if self.variante_filtro:
45
+ payload["variante_filtro"] = self.variante_filtro
46
+ return payload
47
+
48
+ @classmethod
49
+ def de_payload(cls, payload: dict[str, Any]) -> "Coluna":
50
+ return cls(
51
+ chave=payload["chave"],
52
+ cabecalho=payload["cabecalho"],
53
+ tipo=payload.get("tipo", TipoColuna.TEXTO),
54
+ filtravel=payload.get("filtravel", False),
55
+ variante_filtro=payload.get("variante_filtro"),
56
+ )
57
+
58
+
59
+ @dataclass(slots=True)
60
+ class Fonte:
61
+ id: str
62
+ slug: str
63
+ nome: str
64
+ grupo: str | None = None
65
+ descricao: str = ""
66
+ independente: bool = False
67
+ aberto: bool = False
68
+ dono_id: str | None = None
69
+ criado_em: str | None = None
70
+
71
+ @classmethod
72
+ def de_payload(cls, payload: dict[str, Any]) -> "Fonte":
73
+ return cls(
74
+ id=payload.get("id", ""),
75
+ slug=payload.get("slug", ""),
76
+ nome=payload.get("nome", ""),
77
+ grupo=payload.get("grupo"),
78
+ descricao=payload.get("descricao", ""),
79
+ independente=payload.get("independente", False),
80
+ aberto=payload.get("aberto", False),
81
+ dono_id=payload.get("dono_id"),
82
+ criado_em=payload.get("criado_em"),
83
+ )
84
+
85
+
86
+ @dataclass(slots=True)
87
+ class ColunaRelacao:
88
+ origem: str
89
+ destino: str
90
+
91
+ def para_payload(self) -> dict[str, Any]:
92
+ return {"origem": self.origem, "destino": self.destino}
93
+
94
+ @classmethod
95
+ def de_payload(cls, payload: dict[str, Any]) -> "ColunaRelacao":
96
+ return cls(origem=payload["origem"], destino=payload["destino"])
97
+
98
+
99
+ @dataclass(slots=True)
100
+ class DestinoRelacao:
101
+ fonte: str
102
+ grupo: str | None = None
103
+ independente: bool = False
104
+
105
+ def para_payload(self) -> dict[str, Any]:
106
+ payload: dict[str, Any] = {"fonte": self.fonte}
107
+ if self.grupo:
108
+ payload["grupo"] = self.grupo
109
+ if self.independente:
110
+ payload["independente"] = True
111
+ return payload
112
+
113
+ @classmethod
114
+ def de_payload(cls, payload: dict[str, Any]) -> "DestinoRelacao":
115
+ return cls(
116
+ fonte=payload.get("fonte", ""),
117
+ grupo=payload.get("grupo"),
118
+ independente=payload.get("independente", False),
119
+ )
120
+
121
+
122
+ @dataclass(slots=True)
123
+ class RelacaoFonte:
124
+ destino: DestinoRelacao
125
+ colunas: list[ColunaRelacao]
126
+ destino_nome: str | None = None
127
+ criado_em: str | None = None
128
+
129
+ def para_payload(self) -> dict[str, Any]:
130
+ return {
131
+ "destino": self.destino.para_payload(),
132
+ "colunas": [coluna.para_payload() for coluna in self.colunas],
133
+ }
134
+
135
+ @classmethod
136
+ def de_payload(cls, payload: dict[str, Any]) -> "RelacaoFonte":
137
+ return cls(
138
+ destino=DestinoRelacao.de_payload(payload.get("destino") or {}),
139
+ colunas=[ColunaRelacao.de_payload(coluna) for coluna in payload.get("colunas") or []],
140
+ destino_nome=payload.get("destino_nome"),
141
+ criado_em=payload.get("criado_em"),
142
+ )
143
+
144
+
145
+ @dataclass(slots=True)
146
+ class DadosPainel:
147
+ colunas: list[Coluna]
148
+ linhas: list[Linha]
149
+ atualizado_em: datetime | None = None
150
+
151
+ def para_dataframe(self) -> pd.DataFrame:
152
+ chaves = [coluna.chave for coluna in self.colunas]
153
+ return pd.DataFrame(self.linhas).reindex(columns=chaves)
154
+
155
+
156
+ _CHECAGENS_TIPO: list[tuple[Callable[[Any], bool], TipoColuna]] = [
157
+ (pdtypes.is_bool_dtype, TipoColuna.BOOLEANO),
158
+ (pdtypes.is_integer_dtype, TipoColuna.INTEIRO),
159
+ (pdtypes.is_float_dtype, TipoColuna.NUMERO),
160
+ (pdtypes.is_datetime64_any_dtype, TipoColuna.DATA_HORA),
161
+ ]
162
+
163
+
164
+ def colunas_de_dataframe(frame: pd.DataFrame) -> list[Coluna]:
165
+ return [
166
+ Coluna(chave=str(nome), cabecalho=str(nome), tipo=_tipo_para(frame[nome]))
167
+ for nome in frame.columns
168
+ ]
169
+
170
+
171
+ def linhas_de_dataframe(frame: pd.DataFrame) -> list[Linha]:
172
+ return [
173
+ {str(chave): _valor_json(valor) for chave, valor in registro.items()}
174
+ for registro in frame.to_dict(orient="records")
175
+ ]
176
+
177
+
178
+ def _tipo_para(series: "pd.Series[Any]") -> TipoColuna:
179
+ for verificacao, tipo in _CHECAGENS_TIPO:
180
+ if verificacao(series):
181
+ return tipo
182
+ return TipoColuna.TEXTO
183
+
184
+
185
+ def _valor_json(valor: Any) -> Any:
186
+ if valor is None or valor is pd.NaT:
187
+ return None
188
+ if isinstance(valor, pd.Timestamp):
189
+ return valor.isoformat()
190
+ if isinstance(valor, np.generic):
191
+ valor = valor.item()
192
+ if isinstance(valor, float) and math.isnan(valor):
193
+ return None
194
+ return valor
195
+
196
+
197
+ class OperacaoAgregacao(StrEnum):
198
+ NENHUMA = "none"
199
+ SOMA = "sum"
200
+ MEDIA = "avg"
201
+ MINIMO = "min"
202
+ MAXIMO = "max"
203
+ CONTAGEM = "count"
204
+
205
+
206
+ class TipoWidgetNativo(StrEnum):
207
+ METRICA = "metric"
208
+ GRAFICO_LINHA = "lineChart"
209
+ GRAFICO_BARRAS = "barChart"
210
+ GRAFICO_AREA = "areaChart"
211
+ GRAFICO_PIZZA = "pieChart"
212
+ TABELA = "table"
213
+ SELO = "badge"
214
+ STATUS = "status"
215
+ CARTAO = "card"
216
+
217
+
218
+ TipoWidget = str
219
+ PREFIXO_TIPO_PLUGIN = "plugin:"
220
+ TIPOS_WIDGET_NATIVOS: frozenset[str] = frozenset(tipo.value for tipo in TipoWidgetNativo)
221
+
222
+
223
+ @dataclass(slots=True)
224
+ class Vinculo:
225
+ x: str | None = None
226
+ series: list[str] | None = None
227
+ valor: str | None = None
228
+ categoria: str | None = None
229
+ agregacao: OperacaoAgregacao | str | None = None
230
+ filtro: dict[str, Any] | None = None
231
+
232
+ def para_payload(self) -> dict[str, Any]:
233
+ payload: dict[str, Any] = {}
234
+ if self.x:
235
+ payload["x"] = self.x
236
+ if self.series:
237
+ payload["series"] = list(self.series)
238
+ if self.valor:
239
+ payload["valor"] = self.valor
240
+ if self.categoria:
241
+ payload["categoria"] = self.categoria
242
+ if self.agregacao:
243
+ payload["agregacao"] = str(self.agregacao)
244
+ if self.filtro:
245
+ payload["filtro"] = dict(self.filtro)
246
+ return payload
247
+
248
+ @classmethod
249
+ def de_payload(cls, payload: dict[str, Any]) -> "Vinculo":
250
+ return cls(
251
+ x=payload.get("x"),
252
+ series=payload.get("series"),
253
+ valor=payload.get("valor"),
254
+ categoria=payload.get("categoria"),
255
+ agregacao=payload.get("agregacao"),
256
+ filtro=payload.get("filtro"),
257
+ )
258
+
259
+
260
+ @dataclass(slots=True)
261
+ class PosicaoWidget:
262
+ x: int
263
+ y: int
264
+ w: int
265
+ h: int
266
+
267
+ def para_payload(self) -> dict[str, Any]:
268
+ return {"x": self.x, "y": self.y, "w": self.w, "h": self.h}
269
+
270
+ @classmethod
271
+ def de_payload(cls, payload: dict[str, Any]) -> "PosicaoWidget":
272
+ return cls(x=payload["x"], y=payload["y"], w=payload["w"], h=payload["h"])
273
+
274
+
275
+ @dataclass(slots=True)
276
+ class Widget:
277
+ id: str
278
+ tipo: TipoWidget
279
+ em: PosicaoWidget
280
+ titulo: str | None = None
281
+ fonte: str | None = None
282
+ vinculo: Vinculo | None = None
283
+ config: dict[str, Any] | None = None
284
+
285
+ def para_payload(self) -> dict[str, Any]:
286
+ payload: dict[str, Any] = {
287
+ "id": self.id,
288
+ "tipo": str(self.tipo),
289
+ "em": self.em.para_payload(),
290
+ }
291
+ if self.titulo:
292
+ payload["titulo"] = self.titulo
293
+ if self.fonte:
294
+ payload["fonte"] = self.fonte
295
+ if self.vinculo is not None:
296
+ vinculo = self.vinculo.para_payload()
297
+ if vinculo:
298
+ payload["vinculo"] = vinculo
299
+ if self.config:
300
+ payload["config"] = dict(self.config)
301
+ return payload
302
+
303
+ @classmethod
304
+ def de_payload(cls, payload: dict[str, Any]) -> "Widget":
305
+ vinculo = payload.get("vinculo")
306
+ return cls(
307
+ id=payload["id"],
308
+ tipo=payload["tipo"],
309
+ em=PosicaoWidget.de_payload(payload["em"]),
310
+ titulo=payload.get("titulo"),
311
+ fonte=payload.get("fonte"),
312
+ vinculo=Vinculo.de_payload(vinculo) if vinculo else None,
313
+ config=payload.get("config"),
314
+ )
315
+
316
+
317
+ @dataclass(slots=True)
318
+ class GradeWidgets:
319
+ colunas: int
320
+
321
+ def para_payload(self) -> dict[str, Any]:
322
+ return {"colunas": self.colunas}
323
+
324
+ @classmethod
325
+ def de_payload(cls, payload: dict[str, Any]) -> "GradeWidgets":
326
+ return cls(colunas=payload["colunas"])
327
+
328
+
329
+ @dataclass(slots=True)
330
+ class Aba:
331
+ id: str
332
+ rotulo: str
333
+ grade: GradeWidgets
334
+ widgets: list[Widget] = field(default_factory=list)
335
+ icone: str | None = None
336
+
337
+ def para_payload(self) -> dict[str, Any]:
338
+ payload: dict[str, Any] = {
339
+ "id": self.id,
340
+ "rotulo": self.rotulo,
341
+ "grade": self.grade.para_payload(),
342
+ "widgets": [widget.para_payload() for widget in self.widgets],
343
+ }
344
+ if self.icone:
345
+ payload["icone"] = self.icone
346
+ return payload
347
+
348
+ @classmethod
349
+ def de_payload(cls, payload: dict[str, Any]) -> "Aba":
350
+ return cls(
351
+ id=payload["id"],
352
+ rotulo=payload["rotulo"],
353
+ grade=GradeWidgets.de_payload(payload["grade"]),
354
+ widgets=[Widget.de_payload(widget) for widget in payload.get("widgets", [])],
355
+ icone=payload.get("icone"),
356
+ )
357
+
358
+
359
+ @dataclass(slots=True)
360
+ class FontePainel:
361
+ id: str
362
+ fonte: str
363
+ grupo: str | None = None
364
+
365
+ def para_payload(self) -> dict[str, Any]:
366
+ payload: dict[str, Any] = {"id": self.id, "fonte": self.fonte}
367
+ if self.grupo:
368
+ payload["grupo"] = self.grupo
369
+ return payload
370
+
371
+ @classmethod
372
+ def de_payload(cls, payload: dict[str, Any]) -> "FontePainel":
373
+ return cls(id=payload["id"], fonte=payload["fonte"], grupo=payload.get("grupo"))
374
+
375
+
376
+ @dataclass(slots=True)
377
+ class DefinicaoPainel:
378
+ fontes: list[FontePainel] = field(default_factory=list)
379
+ abas: list[Aba] = field(default_factory=list)
380
+ versao_esquema: int = 1
381
+
382
+ def para_payload(self) -> dict[str, Any]:
383
+ return {
384
+ "versao_esquema": self.versao_esquema,
385
+ "fontes": [fonte.para_payload() for fonte in self.fontes],
386
+ "abas": [aba.para_payload() for aba in self.abas],
387
+ }
388
+
389
+ @classmethod
390
+ def de_payload(cls, payload: dict[str, Any]) -> "DefinicaoPainel":
391
+ return cls(
392
+ fontes=[FontePainel.de_payload(fonte) for fonte in payload.get("fontes", [])],
393
+ abas=[Aba.de_payload(aba) for aba in payload.get("abas", [])],
394
+ versao_esquema=payload.get("versao_esquema", 1),
395
+ )
396
+
397
+
398
+ @dataclass(slots=True)
399
+ class Usuario:
400
+ id: str
401
+ nome: str
402
+ email: str
403
+ documento: str = ""
404
+ telefone: str = ""
405
+ papeis: list[str] = field(default_factory=list)
406
+ criado_em: str | None = None
407
+ atualizado_em: str | None = None
408
+
409
+ @classmethod
410
+ def de_payload(cls, payload: dict[str, Any]) -> "Usuario":
411
+ return cls(
412
+ id=payload.get("id", ""),
413
+ nome=payload.get("nome", ""),
414
+ email=payload.get("email", ""),
415
+ documento=payload.get("documento", ""),
416
+ telefone=payload.get("telefone", ""),
417
+ papeis=payload.get("papeis", []),
418
+ criado_em=payload.get("criado_em"),
419
+ atualizado_em=payload.get("atualizado_em"),
420
+ )
421
+
422
+
423
+ @dataclass(slots=True)
424
+ class ResultadoLogin:
425
+ token: str
426
+ usuario: Usuario
datamais_api/py.typed ADDED
File without changes
@@ -0,0 +1,199 @@
1
+ Metadata-Version: 2.4
2
+ Name: datamais-api
3
+ Version: 0.3.0
4
+ Summary: Cliente Python da API DataMais, feito para bots de carga de dados.
5
+ Author: SECONV-RR
6
+ License-Expression: LicenseRef-Proprietary
7
+ Project-URL: Repository, https://github.com/seconv-rr/datamais-lib-python
8
+ Project-URL: Issues, https://github.com/seconv-rr/datamais-lib-python/issues
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Natural Language :: Portuguese (Brazilian)
11
+ Classifier: Programming Language :: Python :: 3.13
12
+ Classifier: Typing :: Typed
13
+ Requires-Python: >=3.13
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: httpx>=0.28.1
17
+ Requires-Dist: pandas>=3.0.1
18
+ Dynamic: license-file
19
+
20
+ # datamais-api-python
21
+
22
+ Cliente Python da API DataMais da **SECONV-RR** (Governo do Estado de
23
+ Roraima), feito para tornar triviais os bots de carga de dados ("cargas"):
24
+ autentique com uma chave de API, leia as linhas atuais de uma fonte, envie um
25
+ snapshot de substituição completo.
26
+
27
+ O código é escrito em português sem acentos, acompanhando a API e o seu wire;
28
+ apenas o nome de distribuição e de import continua `datamais_api`.
29
+
30
+ ## Instalação
31
+
32
+ ```sh
33
+ uv add datamais-api
34
+ ```
35
+
36
+ Ou direto do repositório:
37
+
38
+ ```sh
39
+ uv add git+ssh://git@github.com/seconv-rr/datamais-api-python.git
40
+ ```
41
+
42
+ ## Configuração
43
+
44
+ O cliente lê duas variáveis de ambiente; argumentos do construtor têm
45
+ precedência sobre elas:
46
+
47
+ | Variável | Propósito |
48
+ | --- | --- |
49
+ | `DATAMAIS_BASE_URL` | URL base da API (ex.: `https://api.datamais.example`) |
50
+ | `DATAMAIS_API_KEY` | Segredo da chave de API (`dmk_...`) com concessões `view`/`manage` nas fontes alvo |
51
+
52
+ Sem `DATAMAIS_BASE_URL`, a construção do cliente levanta `ErroConfigAusente`.
53
+ `DATAMAIS_API_KEY` é opcional: omita-a para clientes somente-sessão, que
54
+ autenticam com `entrar` e um token `Bearer` em vez de uma chave de máquina.
55
+
56
+ ## Início rápido: um bot de carga
57
+
58
+ ```python
59
+ from datamais_api import ClienteDatamais, Coluna, TipoColuna
60
+
61
+ colunas = [
62
+ Coluna("convenio", "Convênio", TipoColuna.TEXTO, filtravel=True),
63
+ Coluna("valor_global", "Valor Global", TipoColuna.DINHEIRO),
64
+ Coluna("assinatura", "Assinatura", TipoColuna.DATA),
65
+ ]
66
+ linhas = [
67
+ {"convenio": "923456/2026", "valor_global": 150000.0, "assinatura": "2026-07-01"},
68
+ ]
69
+
70
+ with ClienteDatamais() as cliente:
71
+ cliente.substituir_dados_fonte("geral", "programas", colunas, linhas)
72
+ dados = cliente.obter_dados_fonte("geral", "programas")
73
+ print(dados.atualizado_em, len(dados.linhas))
74
+ ```
75
+
76
+ `substituir_dados_fonte` substitui atomicamente o catálogo de colunas e as
77
+ linhas da fonte (`PUT /v1/grupos/{grupo}/fontes/{slug}/dados`); a chave de API
78
+ precisa possuir `dataset:<grupo>:<slug>:manage` (ou a equivalente em nível de
79
+ grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
80
+ `dataset:<grupo>:<slug>:view`, a menos que a fonte seja pública.
81
+
82
+ `criar_fonte` cadastra uma fonte em um grupo (`POST /v1/grupos/{grupo}/fontes`),
83
+ para que um bot de carga possa criar a fonte que está prestes a preencher:
84
+
85
+ ```python
86
+ from datamais_api import ClienteDatamais, ErroConflito
87
+
88
+ with ClienteDatamais() as cliente:
89
+ try:
90
+ cliente.criar_fonte("geral", "programas", "Programas", descricao="SICONV")
91
+ except ErroConflito:
92
+ pass
93
+ cliente.substituir_dados_fonte("geral", "programas", colunas, linhas)
94
+ ```
95
+
96
+ `acoes` tem como padrão `ACOES_FONTE_PADRAO` (`view`, `manage`); a API sempre
97
+ acrescenta `admin`. A chave de API precisa de `group:<grupo>:manage` ou do
98
+ próprio `dataset:<grupo>:<slug>:manage` da fonte, e o grupo ainda precisa
99
+ existir e ter dono — uma chave não é um usuário, então ela nunca pode criar o
100
+ grupo. Uma fonte que já existe volta como `ErroConflito`; um grupo inexistente
101
+ ou sem dono, como `ErroValidacao` (`422`).
102
+
103
+ ## Layout de painel (autoria)
104
+
105
+ Além das cargas de fonte, o cliente lê e escreve o **layout** de um painel — a
106
+ `DefinicaoPainel` (abas, grade, widgets, fontes) guardada como JSONB:
107
+
108
+ ```python
109
+ from datamais_api import ClienteDatamais
110
+
111
+ with ClienteDatamais() as cliente:
112
+ cliente.entrar("autora@example.com", "segredo") # escrever layout exige sessão
113
+ definicao = cliente.obter_layout("geral", "convenios")
114
+ if definicao is not None:
115
+ cliente.substituir_layout("geral", "convenios", definicao)
116
+ ```
117
+
118
+ A autenticação é resolvida a cada requisição: um `token` de sessão explícito
119
+ (ou um obtido com `entrar`) é enviado como `Authorization: Bearer`; caso
120
+ contrário vai o `X-API-Chave`. `obter_layout` aceita qualquer um dos dois (ou
121
+ nenhum, para painéis públicos) e retorna `None` quando o painel não tem
122
+ layout. `substituir_layout` é um **endpoint de autoria** — somente sessão,
123
+ então levanta `ErroSessaoObrigatoria` sem um `entrar`/`token`, e a API nunca
124
+ aceita uma chave de API para ele.
125
+
126
+ `entrar` retorna um `ResultadoLogin` (token mais `Usuario`) e `None` quando as
127
+ credenciais são recusadas — uma senha errada é um resultado esperado, não uma
128
+ exceção. `eu` lê a sessão de volta da mesma forma, e `sair` descarta o token.
129
+
130
+ Compor uma `DefinicaoPainel` em Python é trabalho do SDK de autoria irmão, o
131
+ [`datamais-sdk`](../datamais-sdk-python), que constrói e valida a definição e
132
+ a publica através deste cliente.
133
+
134
+ ## pandas
135
+
136
+ `DadosPainel.para_dataframe()` retorna as linhas como um DataFrame ordenado
137
+ pelo catálogo de colunas. Para cargas, `substituir_dados_fonte_de_dataframe`
138
+ envia um DataFrame inteiro em uma única chamada, inferindo o catálogo de
139
+ colunas a partir dos dtypes (bool → `bool`, inteiro → `int`, float →
140
+ `number`, datetime → `datetime`, o resto → `text`), a menos que uma lista
141
+ explícita de `colunas` seja passada. NaN e NaT viram `null`, e timestamps são
142
+ serializados como ISO-8601.
143
+
144
+ ```python
145
+ import pandas as pd
146
+ from datamais_api import ClienteDatamais
147
+
148
+ quadro = pd.read_csv("convenios.csv")
149
+
150
+ with ClienteDatamais() as cliente:
151
+ cliente.substituir_dados_fonte_de_dataframe("geral", "programas", quadro)
152
+ ```
153
+
154
+ Vale a pena passar o catálogo explicitamente sempre que o painel se importa
155
+ com a renderização: a inferência não tem como adivinhar `money`, `date`,
156
+ `link`, `percent` nem quais colunas são `filtravel`.
157
+
158
+ ## Erros
159
+
160
+ Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
161
+ `detalhe` e a lista estruturada `erros` da API:
162
+
163
+ - `ErroAutenticacao` (401) — chave ausente, inválida, expirada ou revogada
164
+ - `ErroProibido` (403) — a chave não possui a permissão exigida
165
+ - `ErroNaoEncontrado` (404) — fonte desconhecida (grupo, slug)
166
+ - `ErroConflito` (409)
167
+ - `ErroValidacao` (422) — colunas/linhas malformadas
168
+ - `ErroAPI` — qualquer outro status não-2xx
169
+
170
+ Todas são subclasses de `ErroAPI`, que por sua vez é subclasse de
171
+ `ErroDatamais`, ao lado de `ErroConfigAusente` e `ErroSessaoObrigatoria`.
172
+
173
+ ## Consumidores
174
+
175
+ - [`datamais-cargas`](../datamais-cargas) — os jobs de carga que alimentam as fontes.
176
+ - [`datamais-sdk`](../datamais-sdk-python) — o SDK de autoria de painéis.
177
+
178
+ ## Publicação
179
+
180
+ Todo push na `main` roda o workflow de release: o python-semantic-release
181
+ calcula a próxima versão a partir dos Conventional Commits, escreve-a em
182
+ `pyproject.toml` e em `src/datamais_api/__init__.py`, cria a tag, atualiza o
183
+ changelog, compila com uv e — somente quando uma nova versão foi cortada —
184
+ publica no PyPI via `uv publish`, usando PyPI Trusted Publishing (sem
185
+ segredos de token).
186
+
187
+ Configuração única no PyPI: adicionar um trusted publisher para o projeto
188
+ `datamais-api` apontando para o repositório `seconv-rr/datamais-api-python` e
189
+ o workflow `release.yml`.
190
+
191
+ ## Desenvolvimento
192
+
193
+ ```sh
194
+ uv sync # instala as dependências
195
+ uv run pytest # testes (offline, transporte mockado)
196
+ uv run ruff check src tests # lint
197
+ uv run ruff format src tests # formatação
198
+ uv run basedpyright src # checagem de tipos
199
+ ```
@@ -0,0 +1,11 @@
1
+ datamais_api/__init__.py,sha256=YdXDzLcU_6tpcc-G3ZRBU2mE9LqJhPn4AZBzg82WngE,1600
2
+ datamais_api/cliente.py,sha256=GO54P_yrd1sq1xtCPeURGrR1bQ0r-ca9k-HrcAXbvXg,7456
3
+ datamais_api/config.py,sha256=lOu2Ij550XyKNsU4njMwbYQC0CM4wiuqub5S5XQOFYw,762
4
+ datamais_api/erros.py,sha256=4Bp_ZGB3zFBCP4hYLyFAPSk3Cu4Wbcvq7YDmqCrJvPA,1901
5
+ datamais_api/modelos.py,sha256=H6xuFaaHwhGErMfGl8fKYgR_4rbdei2MhXAqbk_8pd4,12169
6
+ datamais_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
7
+ datamais_api-0.3.0.dist-info/licenses/LICENSE,sha256=iJYPSReYeJmVs2sdMQx7PtBOH8GPLIvvVqGaK2IWm4A,1971
8
+ datamais_api-0.3.0.dist-info/METADATA,sha256=5ngakDo2g6le4IgHYphD4cmp22f7KWIwjKuiwHPrZYA,7842
9
+ datamais_api-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
10
+ datamais_api-0.3.0.dist-info/top_level.txt,sha256=DXcTmIwV0XeShJshVdVnkdHLuOCIRXNL3rw056dppCE,13
11
+ datamais_api-0.3.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,40 @@
1
+ LICENÇA PROPRIETÁRIA — TODOS OS DIREITOS RESERVADOS
2
+
3
+ Copyright (c) 2026 SECONV-RR — Governo do Estado de Roraima.
4
+
5
+ Este software, seu código-fonte, binários, esquemas de banco de dados,
6
+ documentação e todos os demais materiais associados (o "Software") são de
7
+ propriedade exclusiva do titular acima e constituem software proprietário e
8
+ confidencial, protegido pela Lei nº 9.609/1998 (Lei do Software), pela Lei nº
9
+ 9.610/1998 (Lei de Direitos Autorais) e pelos tratados internacionais
10
+ aplicáveis.
11
+
12
+ NENHUM DIREITO É CONCEDIDO POR ESTE ARQUIVO. Em particular, e sem prejuízo de
13
+ outras restrições:
14
+
15
+ 1. É proibido usar, copiar, reproduzir, modificar, mesclar, publicar,
16
+ distribuir, disponibilizar, sublicenciar, alugar, vender ou de qualquer
17
+ outra forma explorar o Software, no todo ou em parte, sem autorização
18
+ prévia, expressa e por escrito do titular.
19
+
20
+ 2. O acesso ao Software é restrito às pessoas expressamente autorizadas pelo
21
+ titular, exclusivamente para o desenvolvimento, a manutenção e a operação
22
+ do próprio Software no interesse do titular.
23
+
24
+ 3. É proibida a engenharia reversa, descompilação ou desmontagem do Software,
25
+ exceto na estrita medida em que tal restrição seja vedada por lei.
26
+
27
+ 4. Qualquer cópia autorizada do Software deve conservar integralmente este
28
+ aviso de direitos autorais e de propriedade.
29
+
30
+ 5. O Software é fornecido "NO ESTADO EM QUE SE ENCONTRA" (AS IS), sem
31
+ garantias de qualquer natureza, expressas ou implícitas, incluindo, sem
32
+ limitação, garantias de comercialização, adequação a um propósito
33
+ específico e não violação. Em nenhuma hipótese o titular será responsável
34
+ por quaisquer danos decorrentes do uso ou da impossibilidade de uso do
35
+ Software.
36
+
37
+ 6. O descumprimento destas condições sujeita o infrator às sanções civis e
38
+ penais previstas na legislação aplicável.
39
+
40
+ Para solicitar autorização de uso ou licenciamento, contate a SECONV-RR.
@@ -0,0 +1 @@
1
+ datamais_api