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.
- datamais_api/__init__.py +81 -0
- datamais_api/cliente.py +221 -0
- datamais_api/config.py +28 -0
- datamais_api/erros.py +72 -0
- datamais_api/modelos.py +426 -0
- datamais_api/py.typed +0 -0
- datamais_api-0.3.0.dist-info/METADATA +199 -0
- datamais_api-0.3.0.dist-info/RECORD +11 -0
- datamais_api-0.3.0.dist-info/WHEEL +5 -0
- datamais_api-0.3.0.dist-info/licenses/LICENSE +40 -0
- datamais_api-0.3.0.dist-info/top_level.txt +1 -0
datamais_api/__init__.py
ADDED
|
@@ -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
|
+
]
|
datamais_api/cliente.py
ADDED
|
@@ -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 []
|
datamais_api/modelos.py
ADDED
|
@@ -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,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
|