datamais-api 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- datamais_api-0.3.0/LICENSE +40 -0
- datamais_api-0.3.0/PKG-INFO +199 -0
- datamais_api-0.3.0/README.md +180 -0
- datamais_api-0.3.0/pyproject.toml +59 -0
- datamais_api-0.3.0/setup.cfg +4 -0
- datamais_api-0.3.0/src/datamais_api/__init__.py +81 -0
- datamais_api-0.3.0/src/datamais_api/cliente.py +221 -0
- datamais_api-0.3.0/src/datamais_api/config.py +28 -0
- datamais_api-0.3.0/src/datamais_api/erros.py +72 -0
- datamais_api-0.3.0/src/datamais_api/modelos.py +426 -0
- datamais_api-0.3.0/src/datamais_api/py.typed +0 -0
- datamais_api-0.3.0/src/datamais_api.egg-info/PKG-INFO +199 -0
- datamais_api-0.3.0/src/datamais_api.egg-info/SOURCES.txt +18 -0
- datamais_api-0.3.0/src/datamais_api.egg-info/dependency_links.txt +1 -0
- datamais_api-0.3.0/src/datamais_api.egg-info/requires.txt +2 -0
- datamais_api-0.3.0/src/datamais_api.egg-info/top_level.txt +1 -0
- datamais_api-0.3.0/tests/test_cliente.py +354 -0
- datamais_api-0.3.0/tests/test_config.py +55 -0
- datamais_api-0.3.0/tests/test_layout.py +212 -0
- datamais_api-0.3.0/tests/test_pandas.py +130 -0
|
@@ -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,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,180 @@
|
|
|
1
|
+
# datamais-api-python
|
|
2
|
+
|
|
3
|
+
Cliente Python da API DataMais da **SECONV-RR** (Governo do Estado de
|
|
4
|
+
Roraima), feito para tornar triviais os bots de carga de dados ("cargas"):
|
|
5
|
+
autentique com uma chave de API, leia as linhas atuais de uma fonte, envie um
|
|
6
|
+
snapshot de substituição completo.
|
|
7
|
+
|
|
8
|
+
O código é escrito em português sem acentos, acompanhando a API e o seu wire;
|
|
9
|
+
apenas o nome de distribuição e de import continua `datamais_api`.
|
|
10
|
+
|
|
11
|
+
## Instalação
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
uv add datamais-api
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Ou direto do repositório:
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
uv add git+ssh://git@github.com/seconv-rr/datamais-api-python.git
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Configuração
|
|
24
|
+
|
|
25
|
+
O cliente lê duas variáveis de ambiente; argumentos do construtor têm
|
|
26
|
+
precedência sobre elas:
|
|
27
|
+
|
|
28
|
+
| Variável | Propósito |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| `DATAMAIS_BASE_URL` | URL base da API (ex.: `https://api.datamais.example`) |
|
|
31
|
+
| `DATAMAIS_API_KEY` | Segredo da chave de API (`dmk_...`) com concessões `view`/`manage` nas fontes alvo |
|
|
32
|
+
|
|
33
|
+
Sem `DATAMAIS_BASE_URL`, a construção do cliente levanta `ErroConfigAusente`.
|
|
34
|
+
`DATAMAIS_API_KEY` é opcional: omita-a para clientes somente-sessão, que
|
|
35
|
+
autenticam com `entrar` e um token `Bearer` em vez de uma chave de máquina.
|
|
36
|
+
|
|
37
|
+
## Início rápido: um bot de carga
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
from datamais_api import ClienteDatamais, Coluna, TipoColuna
|
|
41
|
+
|
|
42
|
+
colunas = [
|
|
43
|
+
Coluna("convenio", "Convênio", TipoColuna.TEXTO, filtravel=True),
|
|
44
|
+
Coluna("valor_global", "Valor Global", TipoColuna.DINHEIRO),
|
|
45
|
+
Coluna("assinatura", "Assinatura", TipoColuna.DATA),
|
|
46
|
+
]
|
|
47
|
+
linhas = [
|
|
48
|
+
{"convenio": "923456/2026", "valor_global": 150000.0, "assinatura": "2026-07-01"},
|
|
49
|
+
]
|
|
50
|
+
|
|
51
|
+
with ClienteDatamais() as cliente:
|
|
52
|
+
cliente.substituir_dados_fonte("geral", "programas", colunas, linhas)
|
|
53
|
+
dados = cliente.obter_dados_fonte("geral", "programas")
|
|
54
|
+
print(dados.atualizado_em, len(dados.linhas))
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`substituir_dados_fonte` substitui atomicamente o catálogo de colunas e as
|
|
58
|
+
linhas da fonte (`PUT /v1/grupos/{grupo}/fontes/{slug}/dados`); a chave de API
|
|
59
|
+
precisa possuir `dataset:<grupo>:<slug>:manage` (ou a equivalente em nível de
|
|
60
|
+
grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
|
|
61
|
+
`dataset:<grupo>:<slug>:view`, a menos que a fonte seja pública.
|
|
62
|
+
|
|
63
|
+
`criar_fonte` cadastra uma fonte em um grupo (`POST /v1/grupos/{grupo}/fontes`),
|
|
64
|
+
para que um bot de carga possa criar a fonte que está prestes a preencher:
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from datamais_api import ClienteDatamais, ErroConflito
|
|
68
|
+
|
|
69
|
+
with ClienteDatamais() as cliente:
|
|
70
|
+
try:
|
|
71
|
+
cliente.criar_fonte("geral", "programas", "Programas", descricao="SICONV")
|
|
72
|
+
except ErroConflito:
|
|
73
|
+
pass
|
|
74
|
+
cliente.substituir_dados_fonte("geral", "programas", colunas, linhas)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`acoes` tem como padrão `ACOES_FONTE_PADRAO` (`view`, `manage`); a API sempre
|
|
78
|
+
acrescenta `admin`. A chave de API precisa de `group:<grupo>:manage` ou do
|
|
79
|
+
próprio `dataset:<grupo>:<slug>:manage` da fonte, e o grupo ainda precisa
|
|
80
|
+
existir e ter dono — uma chave não é um usuário, então ela nunca pode criar o
|
|
81
|
+
grupo. Uma fonte que já existe volta como `ErroConflito`; um grupo inexistente
|
|
82
|
+
ou sem dono, como `ErroValidacao` (`422`).
|
|
83
|
+
|
|
84
|
+
## Layout de painel (autoria)
|
|
85
|
+
|
|
86
|
+
Além das cargas de fonte, o cliente lê e escreve o **layout** de um painel — a
|
|
87
|
+
`DefinicaoPainel` (abas, grade, widgets, fontes) guardada como JSONB:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from datamais_api import ClienteDatamais
|
|
91
|
+
|
|
92
|
+
with ClienteDatamais() as cliente:
|
|
93
|
+
cliente.entrar("autora@example.com", "segredo") # escrever layout exige sessão
|
|
94
|
+
definicao = cliente.obter_layout("geral", "convenios")
|
|
95
|
+
if definicao is not None:
|
|
96
|
+
cliente.substituir_layout("geral", "convenios", definicao)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
A autenticação é resolvida a cada requisição: um `token` de sessão explícito
|
|
100
|
+
(ou um obtido com `entrar`) é enviado como `Authorization: Bearer`; caso
|
|
101
|
+
contrário vai o `X-API-Chave`. `obter_layout` aceita qualquer um dos dois (ou
|
|
102
|
+
nenhum, para painéis públicos) e retorna `None` quando o painel não tem
|
|
103
|
+
layout. `substituir_layout` é um **endpoint de autoria** — somente sessão,
|
|
104
|
+
então levanta `ErroSessaoObrigatoria` sem um `entrar`/`token`, e a API nunca
|
|
105
|
+
aceita uma chave de API para ele.
|
|
106
|
+
|
|
107
|
+
`entrar` retorna um `ResultadoLogin` (token mais `Usuario`) e `None` quando as
|
|
108
|
+
credenciais são recusadas — uma senha errada é um resultado esperado, não uma
|
|
109
|
+
exceção. `eu` lê a sessão de volta da mesma forma, e `sair` descarta o token.
|
|
110
|
+
|
|
111
|
+
Compor uma `DefinicaoPainel` em Python é trabalho do SDK de autoria irmão, o
|
|
112
|
+
[`datamais-sdk`](../datamais-sdk-python), que constrói e valida a definição e
|
|
113
|
+
a publica através deste cliente.
|
|
114
|
+
|
|
115
|
+
## pandas
|
|
116
|
+
|
|
117
|
+
`DadosPainel.para_dataframe()` retorna as linhas como um DataFrame ordenado
|
|
118
|
+
pelo catálogo de colunas. Para cargas, `substituir_dados_fonte_de_dataframe`
|
|
119
|
+
envia um DataFrame inteiro em uma única chamada, inferindo o catálogo de
|
|
120
|
+
colunas a partir dos dtypes (bool → `bool`, inteiro → `int`, float →
|
|
121
|
+
`number`, datetime → `datetime`, o resto → `text`), a menos que uma lista
|
|
122
|
+
explícita de `colunas` seja passada. NaN e NaT viram `null`, e timestamps são
|
|
123
|
+
serializados como ISO-8601.
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
import pandas as pd
|
|
127
|
+
from datamais_api import ClienteDatamais
|
|
128
|
+
|
|
129
|
+
quadro = pd.read_csv("convenios.csv")
|
|
130
|
+
|
|
131
|
+
with ClienteDatamais() as cliente:
|
|
132
|
+
cliente.substituir_dados_fonte_de_dataframe("geral", "programas", quadro)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Vale a pena passar o catálogo explicitamente sempre que o painel se importa
|
|
136
|
+
com a renderização: a inferência não tem como adivinhar `money`, `date`,
|
|
137
|
+
`link`, `percent` nem quais colunas são `filtravel`.
|
|
138
|
+
|
|
139
|
+
## Erros
|
|
140
|
+
|
|
141
|
+
Toda resposta não-2xx levanta uma exceção tipada carregando `status`,
|
|
142
|
+
`detalhe` e a lista estruturada `erros` da API:
|
|
143
|
+
|
|
144
|
+
- `ErroAutenticacao` (401) — chave ausente, inválida, expirada ou revogada
|
|
145
|
+
- `ErroProibido` (403) — a chave não possui a permissão exigida
|
|
146
|
+
- `ErroNaoEncontrado` (404) — fonte desconhecida (grupo, slug)
|
|
147
|
+
- `ErroConflito` (409)
|
|
148
|
+
- `ErroValidacao` (422) — colunas/linhas malformadas
|
|
149
|
+
- `ErroAPI` — qualquer outro status não-2xx
|
|
150
|
+
|
|
151
|
+
Todas são subclasses de `ErroAPI`, que por sua vez é subclasse de
|
|
152
|
+
`ErroDatamais`, ao lado de `ErroConfigAusente` e `ErroSessaoObrigatoria`.
|
|
153
|
+
|
|
154
|
+
## Consumidores
|
|
155
|
+
|
|
156
|
+
- [`datamais-cargas`](../datamais-cargas) — os jobs de carga que alimentam as fontes.
|
|
157
|
+
- [`datamais-sdk`](../datamais-sdk-python) — o SDK de autoria de painéis.
|
|
158
|
+
|
|
159
|
+
## Publicação
|
|
160
|
+
|
|
161
|
+
Todo push na `main` roda o workflow de release: o python-semantic-release
|
|
162
|
+
calcula a próxima versão a partir dos Conventional Commits, escreve-a em
|
|
163
|
+
`pyproject.toml` e em `src/datamais_api/__init__.py`, cria a tag, atualiza o
|
|
164
|
+
changelog, compila com uv e — somente quando uma nova versão foi cortada —
|
|
165
|
+
publica no PyPI via `uv publish`, usando PyPI Trusted Publishing (sem
|
|
166
|
+
segredos de token).
|
|
167
|
+
|
|
168
|
+
Configuração única no PyPI: adicionar um trusted publisher para o projeto
|
|
169
|
+
`datamais-api` apontando para o repositório `seconv-rr/datamais-api-python` e
|
|
170
|
+
o workflow `release.yml`.
|
|
171
|
+
|
|
172
|
+
## Desenvolvimento
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
uv sync # instala as dependências
|
|
176
|
+
uv run pytest # testes (offline, transporte mockado)
|
|
177
|
+
uv run ruff check src tests # lint
|
|
178
|
+
uv run ruff format src tests # formatação
|
|
179
|
+
uv run basedpyright src # checagem de tipos
|
|
180
|
+
```
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "datamais-api"
|
|
3
|
+
version = "0.3.0"
|
|
4
|
+
description = "Cliente Python da API DataMais, feito para bots de carga de dados."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.13"
|
|
7
|
+
license = "LicenseRef-Proprietary"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
authors = [{ name = "SECONV-RR" }]
|
|
10
|
+
classifiers = [
|
|
11
|
+
"Intended Audience :: Developers",
|
|
12
|
+
"Natural Language :: Portuguese (Brazilian)",
|
|
13
|
+
"Programming Language :: Python :: 3.13",
|
|
14
|
+
"Typing :: Typed",
|
|
15
|
+
]
|
|
16
|
+
dependencies = [
|
|
17
|
+
"httpx>=0.28.1",
|
|
18
|
+
"pandas>=3.0.1",
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
[project.urls]
|
|
22
|
+
Repository = "https://github.com/seconv-rr/datamais-lib-python"
|
|
23
|
+
Issues = "https://github.com/seconv-rr/datamais-lib-python/issues"
|
|
24
|
+
|
|
25
|
+
[build-system]
|
|
26
|
+
requires = ["setuptools>=77"]
|
|
27
|
+
build-backend = "setuptools.build_meta"
|
|
28
|
+
|
|
29
|
+
[tool.setuptools.packages.find]
|
|
30
|
+
where = ["src"]
|
|
31
|
+
|
|
32
|
+
[tool.setuptools.package-data]
|
|
33
|
+
datamais_api = ["py.typed"]
|
|
34
|
+
|
|
35
|
+
[tool.ruff]
|
|
36
|
+
line-length = 99
|
|
37
|
+
|
|
38
|
+
[tool.basedpyright]
|
|
39
|
+
typeCheckingMode = "standard"
|
|
40
|
+
reportDeprecated = "error"
|
|
41
|
+
|
|
42
|
+
[tool.pytest.ini_options]
|
|
43
|
+
testpaths = ["tests"]
|
|
44
|
+
|
|
45
|
+
[dependency-groups]
|
|
46
|
+
dev = [
|
|
47
|
+
"basedpyright>=1.39.8",
|
|
48
|
+
"pandas-stubs>=3.0.3.260530",
|
|
49
|
+
"pytest>=8.4.0",
|
|
50
|
+
"ruff>=0.15.19",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[tool.semantic_release]
|
|
54
|
+
version_toml = ["pyproject.toml:project.version"]
|
|
55
|
+
version_variables = ["src/datamais_api/__init__.py:__version__"]
|
|
56
|
+
build_command = "uv build"
|
|
57
|
+
commit_message = "chore(release): v{version} [skip ci]"
|
|
58
|
+
allow_zero_version = true
|
|
59
|
+
major_on_zero = false
|
|
@@ -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
|
+
]
|