datamais-api 0.3.0__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. datamais_api-0.5.0/PKG-INFO +397 -0
  2. datamais_api-0.5.0/README.md +378 -0
  3. {datamais_api-0.3.0 → datamais_api-0.5.0}/pyproject.toml +1 -1
  4. {datamais_api-0.3.0 → datamais_api-0.5.0}/src/datamais_api/__init__.py +31 -3
  5. datamais_api-0.5.0/src/datamais_api/cliente.py +344 -0
  6. {datamais_api-0.3.0 → datamais_api-0.5.0}/src/datamais_api/erros.py +28 -1
  7. datamais_api-0.5.0/src/datamais_api/eventos.py +45 -0
  8. {datamais_api-0.3.0 → datamais_api-0.5.0}/src/datamais_api/modelos.py +174 -8
  9. datamais_api-0.5.0/src/datamais_api.egg-info/PKG-INFO +397 -0
  10. {datamais_api-0.3.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/SOURCES.txt +3 -0
  11. datamais_api-0.5.0/tests/test_acompanhar.py +369 -0
  12. datamais_api-0.5.0/tests/test_cliente.py +855 -0
  13. datamais_api-0.5.0/tests/test_eventos.py +46 -0
  14. {datamais_api-0.3.0 → datamais_api-0.5.0}/tests/test_layout.py +31 -52
  15. datamais_api-0.3.0/PKG-INFO +0 -199
  16. datamais_api-0.3.0/README.md +0 -180
  17. datamais_api-0.3.0/src/datamais_api/cliente.py +0 -221
  18. datamais_api-0.3.0/src/datamais_api.egg-info/PKG-INFO +0 -199
  19. datamais_api-0.3.0/tests/test_cliente.py +0 -354
  20. {datamais_api-0.3.0 → datamais_api-0.5.0}/LICENSE +0 -0
  21. {datamais_api-0.3.0 → datamais_api-0.5.0}/setup.cfg +0 -0
  22. {datamais_api-0.3.0 → datamais_api-0.5.0}/src/datamais_api/config.py +0 -0
  23. {datamais_api-0.3.0 → datamais_api-0.5.0}/src/datamais_api/py.typed +0 -0
  24. {datamais_api-0.3.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/dependency_links.txt +0 -0
  25. {datamais_api-0.3.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/requires.txt +0 -0
  26. {datamais_api-0.3.0 → datamais_api-0.5.0}/src/datamais_api.egg-info/top_level.txt +0 -0
  27. {datamais_api-0.3.0 → datamais_api-0.5.0}/tests/test_config.py +0 -0
  28. {datamais_api-0.3.0 → datamais_api-0.5.0}/tests/test_pandas.py +0 -0
@@ -0,0 +1,397 @@
1
+ Metadata-Version: 2.4
2
+ Name: datamais-api
3
+ Version: 0.5.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, com o prefixo do proxy reverso (ex.: `https://datamais.example/api/v1`) |
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
+ O cliente não acrescenta prefixo nenhum e coloca cada rota logo depois dessa
54
+ URL. Por isso ela já precisa trazer o caminho que o proxy reverso publica, como
55
+ `/api/v1`.
56
+ `DATAMAIS_API_KEY` é opcional: omita-a para clientes somente-sessão, que
57
+ passam um `token` de sessão em vez de uma chave de máquina (veja
58
+ [Sessão de usuário](#sessão-de-usuário)).
59
+
60
+ ## Início rápido: um bot de carga
61
+
62
+ ```python
63
+ from datamais_api import ClienteDatamais, Coluna, TipoColuna
64
+
65
+ colunas = [
66
+ Coluna("convenio", "Convênio", TipoColuna.TEXTO, filtravel=True),
67
+ Coluna("valor_global", "Valor Global", TipoColuna.DINHEIRO),
68
+ Coluna("assinatura", "Assinatura", TipoColuna.DATA),
69
+ ]
70
+ linhas = [
71
+ {"convenio": "923456/2026", "valor_global": 150000.0, "assinatura": "2026-07-01"},
72
+ ]
73
+
74
+ with ClienteDatamais() as cliente:
75
+ cliente.substituir_dados_fonte("geral", "programas", colunas, linhas)
76
+ dados = cliente.obter_dados_fonte("geral", "programas")
77
+ print(dados.atualizado_em, len(dados.linhas))
78
+ ```
79
+
80
+ `substituir_dados_fonte` substitui atomicamente o catálogo de colunas e as
81
+ linhas da fonte (`PUT /grupos/{grupo}/fontes/{slug}/dados`); a chave de API
82
+ precisa possuir `dataset:<grupo>:<slug>:manage` (ou a equivalente em nível de
83
+ grupo, `group:<grupo>:manage`). `obter_dados_fonte` exige
84
+ `dataset:<grupo>:<slug>:view`, a menos que a fonte seja pública.
85
+
86
+ `Coluna(..., escondida=True)` mantém os valores em cada linha sem mostrar a
87
+ coluna ao usuário, o que serve para chaves técnicas que ligam fontes.
88
+
89
+ `criar_fonte` cadastra uma fonte em um grupo (`POST /grupos/{grupo}/fontes`),
90
+ para que um bot de carga possa criar a fonte que está prestes a preencher:
91
+
92
+ ```python
93
+ from datamais_api import ClienteDatamais, ErroConflito
94
+
95
+ with ClienteDatamais() as cliente:
96
+ try:
97
+ cliente.criar_fonte("geral", "programas", "Programas", descricao="SICONV")
98
+ except ErroConflito:
99
+ pass
100
+ cliente.substituir_dados_fonte("geral", "programas", colunas, linhas)
101
+ ```
102
+
103
+ `acoes` tem como padrão `ACOES_FONTE_PADRAO` (`view`, `manage`); a API sempre
104
+ acrescenta `admin`. A chave de API precisa de `group:<grupo>:manage` ou do
105
+ próprio `dataset:<grupo>:<slug>:manage` da fonte, e o grupo ainda precisa
106
+ existir e ter dono — uma chave não é um usuário, então ela nunca pode criar o
107
+ grupo. Uma fonte que já existe volta como `ErroConflito`; um grupo inexistente
108
+ ou sem dono, como `ErroValidacao` (`422`).
109
+
110
+ ## Consultas no servidor
111
+
112
+ `consultar_fonte` filtra, agrupa, agrega, ordena e junta as linhas de uma fonte
113
+ no servidor e devolve só o resultado
114
+ (`POST /grupos/{grupo}/fontes/{slug}/consulta`). A rota usa POST porque
115
+ leva um corpo, mas não altera nada. Ela pede a mesma permissão de
116
+ `obter_dados_fonte` e aceita as mesmas credenciais: chave de API, sessão ou
117
+ nenhuma, no caso de fontes públicas.
118
+
119
+ ```python
120
+ from datamais_api import (
121
+ AgregacaoConsulta,
122
+ ClienteDatamais,
123
+ Consulta,
124
+ DirecaoOrdem,
125
+ FiltroConsulta,
126
+ OperacaoAgregacaoConsulta,
127
+ OperadorFiltroConsulta,
128
+ OrdemConsulta,
129
+ )
130
+
131
+ consulta = Consulta(
132
+ filtros=[
133
+ FiltroConsulta("assinatura", OperadorFiltroConsulta.MAIOR_IGUAL, "2026-01-01"),
134
+ FiltroConsulta("situacao", OperadorFiltroConsulta.EM, ["vigente", "suspenso"]),
135
+ ],
136
+ agrupar=["municipio"],
137
+ agregacoes=[
138
+ AgregacaoConsulta(OperacaoAgregacaoConsulta.SOMA, "valor_global"),
139
+ AgregacaoConsulta(OperacaoAgregacaoConsulta.CONTAGEM),
140
+ ],
141
+ ordenar=[OrdemConsulta("soma_valor_global", DirecaoOrdem.DESC)],
142
+ limite=10,
143
+ )
144
+
145
+ with ClienteDatamais() as cliente:
146
+ resultado = cliente.consultar_fonte("geral", "programas", consulta)
147
+ print(resultado.etag, resultado.linhas)
148
+ ```
149
+
150
+ Todo campo de `Consulta` é opcional, e o corpo leva só os que você preencher.
151
+ Sem consulta, a chamada devolve as primeiras 1000 linhas da fonte.
152
+
153
+ - `colunas` escolhe as colunas devolvidas e a ordem delas. Não pode ser usada
154
+ junto com `agrupar` ou `agregacoes`.
155
+ - Os `filtros` valem todos ao mesmo tempo. O `valor` segue o formato das
156
+ linhas do `PUT /dados` (datas em `AAAA-MM-DD`, data e hora em RFC 3339), é
157
+ uma lista com `em` e fica de fora com `nulo` e `nao_nulo`.
158
+ - `granularidade` agrupa uma coluna `date` ou `datetime` que também está em
159
+ `agrupar` por período: `GranularidadeConsulta.DIA`, `SEMANA`, `MES`,
160
+ `TRIMESTRE` ou `ANO`. O valor do grupo é o início do período, em UTC. Por
161
+ exemplo, `granularidade={"assinatura": GranularidadeConsulta.MES}` soma por
162
+ mês de assinatura.
163
+ - Cada agregação vira uma coluna chamada `<op>_<coluna>`, como
164
+ `soma_valor_global`. Uma `contagem` sem coluna conta as linhas e se chama só
165
+ `contagem`.
166
+ - `filtros_agregacao` usa o mesmo `FiltroConsulta` de `filtros`, mas filtra o
167
+ resultado das agregações pelo nome delas. Assim dá para ficar só com os
168
+ grupos em que `soma_valor_global` passa de um valor.
169
+ - `ordenar` usa `asc` quando a direção não é informada.
170
+ - `limite` vai de 1 a 10000 (o servidor usa 1000 quando ele falta), e
171
+ `deslocamento` pula até 100000 linhas antes da primeira devolvida.
172
+ - Com `total=True`, o resultado traz em `total` quantas linhas a consulta tem
173
+ antes de `limite` e `deslocamento`, o que ajuda a paginar.
174
+ - `juntar` traz colunas de uma fonte de destino de uma relação já declarada.
175
+ `JuncaoConsulta.fonte` é um `DestinoRelacao`, o mesmo tipo usado em
176
+ `definir_relacoes_fonte`.
177
+ - O servidor aceita no máximo 20 filtros, 5 colunas em `agrupar`, 10
178
+ agregações, 10 filtros de agregação e 3 junções.
179
+
180
+ O resultado é o mesmo `DadosPainel` de `obter_dados_fonte`, com `colunas`,
181
+ `linhas`, `atualizado_em`, `etag`, `total` e `sincronizando`, então os dois
182
+ podem ser usados do mesmo jeito, inclusive com `para_dataframe()`. Quando uma
183
+ linha não tem valor em uma coluna, a chave fica ausente do dicionário.
184
+ `sincronizando` é `True` enquanto alguma fonte envolvida se atualiza a partir
185
+ da origem externa em segundo plano. Nesse caso o resultado ainda usa a versão
186
+ anterior, e vale ler de novo em instantes.
187
+
188
+ Para não baixar de novo um resultado que não mudou, passe o `etag` da resposta
189
+ anterior. O cliente envia `If-None-Match`, e `consultar_fonte` devolve `None`
190
+ quando o servidor responde 304:
191
+
192
+ ```python
193
+ with ClienteDatamais() as cliente:
194
+ anterior = cliente.consultar_fonte("geral", "programas", consulta)
195
+ novo = cliente.consultar_fonte("geral", "programas", consulta, etag=anterior.etag)
196
+ resultado = novo if novo is not None else anterior
197
+ ```
198
+
199
+ Um corpo inválido levanta `ErroValidacao`, e cada item de `erros` traz o campo
200
+ em `location` (por exemplo `body.filtros[0].coluna`) e o motivo em `message`.
201
+ Uma consulta que passa do tempo limite do servidor levanta
202
+ `ErroServicoIndisponivel` (503). Um servidor que não habilitou a rota responde
203
+ 404, como acontece com uma fonte desconhecida.
204
+
205
+ ## Dados que se atualizam em segundo plano
206
+
207
+ Uma fonte ligada a uma API externa se atualiza sozinha quando é lida depois de
208
+ vencido o intervalo dela. A leitura responde na hora com a versão anterior, com
209
+ `sincronizando=True`. Fontes ligadas a uma planilha do Google se atualizam
210
+ dentro da própria leitura, então nunca chegam com `sincronizando=True`.
211
+
212
+ Para receber a versão nova sem ler de novo, use os métodos `acompanhar_*`. Eles
213
+ mantêm uma conexão aberta (Server-Sent Events) e devolvem um iterador:
214
+
215
+ ```python
216
+ from datamais_api import ClienteDatamais, DadosPainel, FalhaSincronizacao
217
+
218
+ with ClienteDatamais() as cliente:
219
+ for evento in cliente.acompanhar_dados_fonte("geral", "programas"):
220
+ match evento:
221
+ case DadosPainel():
222
+ print(evento.etag, len(evento.linhas), evento.sincronizando)
223
+ case FalhaSincronizacao():
224
+ print(evento.mensagem)
225
+ ```
226
+
227
+ | Método | Rota | Credenciais |
228
+ | --- | --- | --- |
229
+ | `acompanhar_dados_fonte(grupo, slug)` | `GET /grupos/{grupo}/fontes/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (fonte pública) |
230
+ | `acompanhar_dados_fonte_independente(slug)` | `GET /fontes/independentes/{slug}/dados/eventos` | só sessão |
231
+ | `acompanhar_dados_painel(grupo, slug)` | `GET /grupos/{grupo}/paineis/{slug}/dados/eventos` | chave de API, sessão ou nenhuma (painel público) |
232
+
233
+ Cada rota pede a mesma permissão da leitura comum que corresponde a ela.
234
+
235
+ O primeiro item traz os dados atuais. Quando nada está se atualizando, ele é o
236
+ único. Se vier com `sincronizando=True`, chega mais um: os dados novos, com
237
+ `sincronizando=False`, ou uma `FalhaSincronizacao`. Depois de uma falha, os
238
+ dados que já chegaram são a última versão boa, e a `mensagem` é uma frase
239
+ genérica que pode ser mostrada ao usuário final.
240
+
241
+ - Nas fontes, cada item de dados é um `DadosPainel`, como o de
242
+ `obter_dados_fonte`, e o `etag` é o mesmo da leitura comum.
243
+ - No painel, cada item de dados é um `DadosFontesPainel`, como o de
244
+ `obter_dados_painel`. O segundo item sempre vem e traz os dados novos de
245
+ todas as entradas que se atualizaram. Se algumas entradas falharem, chega
246
+ depois uma `FalhaSincronizacao` com os ids delas em `fontes`.
247
+
248
+ O iterador termina quando o servidor avisa o fim do fluxo, e a conexão fecha
249
+ nesse momento. Se a conexão cair antes, ele termina sem erro e os itens já
250
+ recebidos continuam valendo. Não reconecte em seguida: cada conexão nova é uma
251
+ leitura nova e pode disparar outra atualização. Sair do `for` antes do fim
252
+ também fecha a conexão. Se você guardar o iterador numa variável e parar de
253
+ consumi-lo no meio, chame `close()` nele.
254
+
255
+ A requisição só sai na primeira volta do `for` (ou no primeiro `next()`). Uma
256
+ resposta de erro, como 403, 404, 500 ou 429 quando um chamador anônimo passa do
257
+ limite, levanta a exceção tipada de sempre antes de qualquer item. Sem sessão,
258
+ `acompanhar_dados_fonte_independente` levanta `ErroSessaoObrigatoria` já na
259
+ chamada. O servidor encerra o fluxo no máximo no tempo limite de busca dele
260
+ (30 s por padrão) depois do primeiro item, e o cliente espera até 90 s por cada
261
+ item, ou o `timeout` do cliente, se ele for maior.
262
+
263
+ `obter_dados_painel` lê de uma vez os dados de todas as entradas de fonte de um
264
+ painel (`GET /grupos/{grupo}/paineis/{slug}/dados`). `fontes` é indexado
265
+ pelo id da entrada, `negado` lista as entradas que o chamador não pode ler e
266
+ `relacoes` traz as relações entre as entradas como `RelacaoPainel`. Essa
267
+ leitura também dispara a atualização das fontes do painel, e `sincronizando`
268
+ fica `True` quando alguma delas está se atualizando em segundo plano. Nesse
269
+ caso, `acompanhar_dados_painel` entrega a versão nova.
270
+
271
+ ## Layout de painel (autoria)
272
+
273
+ Além das cargas de fonte, o cliente lê e escreve o **layout** de um painel — a
274
+ `DefinicaoPainel` (abas, grade, widgets, fontes) guardada como JSONB:
275
+
276
+ ```python
277
+ from datamais_api import ClienteDatamais
278
+
279
+ with ClienteDatamais() as cliente:
280
+ definicao = cliente.obter_layout("geral", "convenios")
281
+ if definicao is not None:
282
+ cliente.substituir_layout("geral", "convenios", definicao)
283
+ ```
284
+
285
+ `obter_layout` aceita chave de API, sessão ou nenhuma credencial (painéis
286
+ públicos) e retorna `None` quando o painel ainda não tem layout.
287
+ `substituir_layout` aceita sessão ou uma chave de API com
288
+ `panel:<grupo>:<slug>:manage` ou `group:<grupo>:manage`. O layout gravado por
289
+ uma chave fica sem autor.
290
+
291
+ Compor uma `DefinicaoPainel` em Python é trabalho do SDK de autoria irmão, o
292
+ [`datamais-sdk`](../datamais-sdk-python), que constrói e valida a definição e
293
+ a publica através deste cliente.
294
+
295
+ ## Sessão de usuário
296
+
297
+ O login na API é feito pelo Zitadel (OIDC) no navegador, então esta lib não
298
+ faz login por senha. Quem já tem o token de sessão de um usuário passa ele no
299
+ construtor:
300
+
301
+ ```python
302
+ with ClienteDatamais(token=token_da_sessao) as cliente:
303
+ usuario = cliente.eu()
304
+ ```
305
+
306
+ A autenticação é resolvida a cada requisição: o `token` vai como
307
+ `Authorization: Bearer` e, sem ele, vai o `X-API-Chave`. As rotas que só
308
+ aceitam sessão (as de fontes independentes) levantam `ErroSessaoObrigatoria`
309
+ sem token, antes de fazer a requisição.
310
+
311
+ `eu` devolve o `Usuario` da sessão, ou `None` quando ela não vale mais.
312
+ `eu(token)` usa outro token só naquela chamada. `sair` revoga a sessão na API
313
+ e descarta o token do cliente.
314
+
315
+ ## pandas
316
+
317
+ `DadosPainel.para_dataframe()` retorna as linhas como um DataFrame ordenado
318
+ pelo catálogo de colunas. Para cargas, `substituir_dados_fonte_de_dataframe`
319
+ envia um DataFrame inteiro em uma única chamada, inferindo o catálogo de
320
+ colunas a partir dos dtypes (bool → `bool`, inteiro → `int`, float →
321
+ `number`, datetime → `datetime`, o resto → `text`), a menos que uma lista
322
+ explícita de `colunas` seja passada. NaN e NaT viram `null`, e timestamps são
323
+ serializados como ISO-8601.
324
+
325
+ ```python
326
+ import pandas as pd
327
+ from datamais_api import ClienteDatamais
328
+
329
+ quadro = pd.read_csv("convenios.csv")
330
+
331
+ with ClienteDatamais() as cliente:
332
+ cliente.substituir_dados_fonte_de_dataframe("geral", "programas", quadro)
333
+ ```
334
+
335
+ Vale a pena passar o catálogo explicitamente sempre que o painel se importa
336
+ com a renderização: a inferência não tem como adivinhar `money`, `date`,
337
+ `link`, `percent` nem quais colunas são `filtravel`.
338
+
339
+ ## Erros
340
+
341
+ Toda resposta não-2xx, menos o 304, levanta uma exceção tipada carregando
342
+ `status`, `detalhe` e a lista estruturada `erros` da API:
343
+
344
+ - `ErroRedirecionamento` (3xx, menos 304)
345
+ - `ErroAutenticacao` (401) — chave ausente, inválida, expirada ou revogada
346
+ - `ErroProibido` (403) — a chave não possui a permissão exigida
347
+ - `ErroNaoEncontrado` (404) — fonte desconhecida (grupo, slug)
348
+ - `ErroConflito` (409)
349
+ - `ErroValidacao` (422) — colunas/linhas malformadas
350
+ - `ErroServicoIndisponivel` (503)
351
+ - `ErroAPI` — qualquer outro status não-2xx
352
+
353
+ Todas são subclasses de `ErroAPI`, que por sua vez é subclasse de
354
+ `ErroDatamais`, ao lado de `ErroConfigAusente`, `ErroSessaoObrigatoria` e
355
+ `ErroSegmentoInvalido`.
356
+
357
+ O cliente não segue redirecionamentos, porque seguir um 3xx reenviaria a chave
358
+ de API ou o token de sessão para o endereço do `Location`, que pode ser outro
359
+ host. Qualquer 3xx, menos o 304, levanta `ErroRedirecionamento`, com o `status`
360
+ e o valor do `Location` em `destino` (vazio quando a resposta não tem esse
361
+ cabeçalho). Nesse caso, aponte `DATAMAIS_BASE_URL` (ou `url_base`) para o
362
+ endereço final, por exemplo trocando `http://` por `https://`.
363
+
364
+ Cada `grupo` e `slug` entra na rota como um único segmento codificado, então
365
+ `/`, `?`, `#`, `%` e espaço não mudam a rota chamada. Um `grupo` ou `slug`
366
+ vazio, `.` ou `..` levanta `ErroSegmentoInvalido` antes de qualquer
367
+ requisição: o httpx resolve `.` e `..` no caminho e um valor vazio deixa `//`
368
+ nele, então a chamada poderia ir para outra rota com as suas credenciais. O
369
+ valor recusado fica em `segmento`.
370
+
371
+ ## Consumidores
372
+
373
+ - [`datamais-cargas`](../datamais-cargas) — os jobs de carga que alimentam as fontes.
374
+ - [`datamais-sdk`](../datamais-sdk-python) — o SDK de autoria de painéis.
375
+
376
+ ## Publicação
377
+
378
+ Todo push na `main` roda o workflow de release: o python-semantic-release
379
+ calcula a próxima versão a partir dos Conventional Commits, escreve-a em
380
+ `pyproject.toml` e em `src/datamais_api/__init__.py`, cria a tag, atualiza o
381
+ changelog, compila com uv e — somente quando uma nova versão foi cortada —
382
+ publica no PyPI via `uv publish`, usando PyPI Trusted Publishing (sem
383
+ segredos de token).
384
+
385
+ Configuração única no PyPI: adicionar um trusted publisher para o projeto
386
+ `datamais-api` apontando para o repositório `seconv-rr/datamais-api-python` e
387
+ o workflow `release.yml`.
388
+
389
+ ## Desenvolvimento
390
+
391
+ ```sh
392
+ uv sync # instala as dependências
393
+ uv run pytest # testes (offline, transporte mockado)
394
+ uv run ruff check src tests # lint
395
+ uv run ruff format src tests # formatação
396
+ uv run basedpyright src # checagem de tipos
397
+ ```