As informações apresentadas nesta página são complementares às
Diretrizes Arquiteturais e às
Diretrizes Arquiteturais do Ministério da Saúde.
Este documento define o escopo de utilização, a arquitetura de referência e os
padrões técnicos para projetos Python sob responsabilidade do Ministério da
Saúde e do Datasus.
A presença do Python na seção de tecnologias desta Wiki não significa que a
linguagem esteja homologada como uma stack de desenvolvimento de propósito
geral. Sua utilização regular está restrita aos contextos definidos nesta
página.
As diretrizes aqui contidas não são exaustivas. Casos omissos deverão ser
analisados previamente pela COATIC.
Python está autorizado, sem necessidade de excepcionalização da linguagem,
exclusivamente para soluções de RPA, ETL, Inteligência Artificial e funções
serverless de responsabilidade pontual e bem definida.Python não integra as stacks homologadas para o desenvolvimento regular de
back-ends, front-ends, APIs, aplicações web ou microsserviços.
O enquadramento será determinado pela finalidade e pela responsabilidade
arquitetural do componente, e não somente pela tecnologia utilizada em sua
implantação. Executar código Python em contêiner, Kubernetes, AWS Lambda ou
outra plataforma serverless não altera, por si só, a natureza da solução.
A autorização da linguagem não dispensa a análise da solução nem o atendimento
às diretrizes de arquitetura, segurança, privacidade, governança de dados,
infraestrutura e DevSecOps aplicáveis ao projeto.
| Uso | Situação | Condição |
|---|---|---|
| RPA e automação de processos | Autorizado | Deve permanecer no escopo de automação |
| ETL | Autorizado | Deve permanecer no escopo de extração, transformação e carga de dados |
| Inteligência Artificial | Autorizado | Deve observar as diretrizes e avaliações específicas de IA |
| Funções serverless | Autorizado com escopo delimitado | Devem ser pontuais e não caracterizar back-end, API ou microsserviço de negócio |
| Back-end, API ou microsserviço | Não autorizado como padrão | Exige excepcionalização prévia |
| Front-end ou aplicação web | Não autorizado como padrão | Exige excepcionalização prévia |
Sem excepcionalização prévia, Python não deverá ser utilizado para:
Frameworks como Django, Flask e FastAPI não estão autorizados como padrão para
o desenvolvimento de back-ends. Frameworks e bibliotecas Python destinados à
construção de interfaces também não estão autorizados como padrão de
front-end.
Qualquer necessidade de utilização de Python fora dos contextos autorizados
deverá ser submetida à análise arquitetural prévia da COATIC, antes do início da
implementação ou da contratação da solução.
A eventual autorização será específica para o caso analisado e não constituirá
homologação geral do Python para back-end, front-end ou outras finalidades.
Nos contextos autorizados, a adoção do Python poderá considerar:
A aplicabilidade dessas características dependerá das bibliotecas, do runtime e
da plataforma aprovados para cada projeto. Elas não ampliam o escopo de
homologação da linguagem.
O projeto oficial do Python não designa uma linha específica como LTS. Conforme
a PEP 602, cada versão estável possui um
ciclo de suporte de longo prazo, composto por uma fase de correções regulares e
outra de correções de segurança.
Para fins desta Wiki, considera-se Python LTS vigente a linha estável mais
recente que:
bugfix pelo projetoA linha LTS vigente está automaticamente autorizada para os contextos
previstos nesta página. Essa autorização não amplia o uso de Python para
back-end, front-end, API ou microsserviço.
Na data desta revisão, 17/11/2026, a linha LTS vigente é Python 3.15.x e
a correção estável mais recente é Python 3.15.2, com suporte oficial da linha
previsto até outubro de 2031. Deverá ser utilizada sempre a versão de correção
estável mais recente disponível.
| Situação | Regra |
|---|---|
| Novos projetos | Deverão utilizar a linha LTS vigente |
| Versão de correção | Deverá ser utilizada a versão patch estável mais recente compatível |
| Linha LTS anterior | Permitida temporariamente durante a transição, enquanto possuir suporte oficial |
| Versão em fase exclusiva de segurança | Não deverá ser adotada em projeto novo |
| Versão alpha, beta ou release candidate | Não autorizada em produção |
| Versão em fim de vida | Não autorizada |
Atualizações de correção dentro da linha LTS vigente estão automaticamente
autorizadas e não exigem excepcionalização da linguagem.
Os projetos deverão:
pyproject.toml a linha de Python compatível;A autorização automática da atualização não dispensa testes, validação pela
esteira DevSecOps e verificação de compatibilidade das dependências.
Quando uma nova linha final e estável atender à definição institucional de LTS,
ela passará a ser autorizada para novos projetos sem necessidade de
excepcionalização da linguagem.
A migração entre linhas deverá incluir:
Projetos existentes poderão permanecer temporariamente na linha anterior
enquanto ela possuir suporte oficial, desde que mantenham dependências seguras,
justificativa técnica e plano de migração registrados.
A autorização da linha LTS não elimina a validação de compatibilidade. Antes da
adoção ou atualização do runtime, deverão ser verificadas:
Quando uma biblioteca homologada ainda não suportar a nova linha, o projeto
poderá permanecer temporariamente na linha anterior ou adotar alternativa
aprovada. A dependência não deverá ser substituída por pacote não avaliado
somente para antecipar a migração.
O código-fonte deverá permanecer no repositório institucional definido para o
projeto e utilizar a esteira DevSecOps aplicável.
Quando houver projeto-base homologado e disponibilizado pela COATIC para o
contexto de utilização, ele deverá ser adotado como ponto de partida. Alterações
estruturais relevantes deverão ser justificadas na documentação da solução.
O repositório não deverá conter ambientes virtuais, credenciais, dados reais ou
sensíveis, modelos binários de grande volume, arquivos temporários, evidências
operacionais ou artefatos produzidos durante a execução. Esquemas, manifestos,
model cards e pequenas fixtures sintéticas utilizadas por testes poderão ser
versionados.
A arquitetura Python deverá separar a entrada da execução, a orquestração do
fluxo, as regras de processamento e as integrações externas. Essa separação
facilita testes, substituição de dependências, rastreabilidade e manutenção.
Consumidores Python de execução permanente e com responsabilidade de negócio
serão considerados serviços de back-end e dependerão de excepcionalização,
ainda que sejam iniciados por fila ou evento.
evento, arquivo ou agendamento
↓
ponto de entrada
↓
validação e identificação
↓
workflow ou pipeline
↓
núcleo de processamento ↔ adaptadores externos
↓
resultado, logs, métricas e evidências
A estrutura deverá ser orientada às responsabilidades da solução e não a
camadas de aplicações web.
nome-do-projeto/
├── src/
│ └── nome_do_projeto/
│ ├── __init__.py
│ ├── entrypoints/
│ ├── workflows/
│ ├── core/
│ ├── adapters/
│ ├── schemas/
│ ├── config/
│ └── observability/
├── tests/
│ ├── unit/
│ ├── integration/
│ └── fixtures/
├── docs/
├── pyproject.toml
├── README.md
├── <arquivo-de-dependências-resolvidas>
└── .gitignore
Diretrizes para a estrutura:
snake_case e não poderá conter hífen;entrypoints deverá conter somente adaptação de entrada e inicialização;workflows deverá coordenar o fluxo sem incorporar detalhes de infraestrutura;core deverá permanecer independente de navegadores, bancos, filas e SDKs deadapters deverá isolar integrações externas;schemas deverá conter contratos e validações de dados;controllers, api, routes, views e templates nãoPython pode ser utilizado para robôs e rotinas de automação de processos,
incluindo interação com sistemas, leitura de arquivos, preenchimento de
formulários e execução de atividades operacionais repetitivas.
As soluções também deverão observar a página
Automação de Processos.
workflows: etapas e decisões do processo automatizado;adapters: integração com navegadores, arquivos e sistemas externos;selectors: seletores de elementos e identificadores de telas;schemas: validação das entradas e saídas da automação;observability: logs, métricas e evidências da execução;Python pode ser utilizado em rotinas de extração, transformação e carga de
dados, executadas em lote, por agendamento ou em resposta a eventos.
As soluções também deverão observar a página
ETL — Extração, Transformação e Carga de Dados.
Uma estrutura específica poderá acrescentar os diretórios extractors,
transformers, loaders, quality e checkpoints ao pacote do projeto.
Python pode ser utilizado em iniciativas de Inteligência Artificial, ciência de
dados e aprendizado de máquina, desde a preparação dos dados até a execução
autorizada de modelos.
As soluções também deverão observar a página
Inteligência Artificial.
O pacote de produção poderá acrescentar os diretórios data_access, features,
training, evaluation e inference. O diretório notebooks, quando
necessário, deverá permanecer na raiz do projeto, separado do pacote de produção
e restrito à exploração e experimentação. Dados reais, modelos e artefatos
volumosos não deverão ser armazenados diretamente no repositório Git.
Python pode ser utilizado em funções serverless, como AWS Lambda ou tecnologia
equivalente, para tarefas pontuais, isoladas e com responsabilidade claramente
definida.
Exemplos de utilização:
Serverless é um modelo de execução, não uma autorização para
desenvolvimento de back-end. Uma função Python somente estará no escopo
regular quando realizar processamento técnico pontual, sem expor API,
constituir serviço de domínio ou permanecer como consumidor contínuo.
Funções serverless Python deverão executar processamento técnico pontual, sem
manter estado de negócio, expor contrato de API, constituir camada de domínio ou
permanecer como consumidor contínuo. A responsabilidade funcional, e não a
duração ou o serviço de nuvem utilizado, determinará o enquadramento.
Uma estrutura específica poderá acrescentar os diretórios handlers e
events, mantendo as regras de processamento fora do handler.
.env com valores reais no repositório;.env somente em desenvolvimento local, quando permitido;Cada projeto deverá utilizar ambiente virtual ou mecanismo equivalente de
isolamento. O diretório do ambiente virtual não deverá ser versionado nem
incorporado ao pacote da aplicação.
pyproject.toml como arquivo principal de metadados e dependênciasrequirements.txt, quando exigido pela plataforma, como artefatoAntes de incluir uma biblioteca, deverão ser avaliados:
Dependências deverão ser atualizadas de forma controlada, com testes e análise
de segurança executados pela esteira. Pacotes abandonados ou obtidos de fontes
não confiáveis não deverão ser utilizados.
snake_case em módulos, funções e variáveis;PascalCase em classes;utils.py, helpers.py e common.py quandoAny;except genérico sem tratamento explícito;print para informaçãoeval, exec ou desserialização insegura de dados nãopickle de origem não confiável;Os logs deverão ser estruturados e conter, quando aplicável:
Logs não deverão registrar senhas, tokens, chaves, conteúdo clínico ou dados
pessoais e sensíveis. Quando um identificador for estritamente necessário à
rastreabilidade, deverão ser aplicados minimização, mascaramento ou
pseudonimização e os controles de acesso e retenção previstos para o projeto.
Cada solução deverá produzir métricas compatíveis com seu contexto, por
exemplo:
Deverá ser possível identificar o código, a configuração, o lote, o evento, o
modelo e os artefatos relacionados a cada execução, conforme o contexto. O prazo
de retenção de logs e evidências deverá seguir a política aplicável ao projeto.
O percentual mínimo de cobertura e as ferramentas oficiais deverão ser
definidos conforme o padrão institucional da esteira.
O repositório deverá possuir README.md e documentação suficiente para
desenvolvimento, operação e continuidade da solução, incluindo:
RPA deverá documentar o processo automatizado e a contingência manual. ETL
deverá documentar origem, destino, regras de transformação e reconciliação. IA
deverá documentar dados, parâmetros, métricas, limitações e versão do modelo.
Serverless deverá documentar contrato do evento, limites e comportamento de
retentativa.
A homologação de uma biblioteca é válida somente para os contextos indicados
nesta página e não amplia a autorização do Python para back-end, front-end,
API, aplicação web ou microsserviço.
Deverão ser utilizadas versões estáveis, mantidas, compatíveis com a linha LTS
vigente e sem vulnerabilidades impeditivas identificadas pela esteira. A versão
selecionada deverá permanecer resolvida e fixada no artefato de implantação.
Quando duas bibliotecas atenderem à mesma responsabilidade, o projeto deverá
selecionar apenas uma delas, salvo justificativa técnica. Exemplos: Selenium ou
Playwright; pandas ou Polars; PyTorch ou TensorFlow.
| Biblioteca ou ferramenta | Finalidade | Situação e condições |
|---|---|---|
| Biblioteca padrão do Python | Arquivos, datas, JSON, CSV, logs e utilitários | Homologada e preferencial quando atender à necessidade |
requests |
Cliente HTTP síncrono | Homologada somente para integrações autorizadas |
httpx |
Cliente HTTP síncrono ou assíncrono | Homologada; não autoriza exposição de API |
pydantic |
Validação de dados e configuração | Homologada para contratos e limites de integração |
tenacity |
Retentativas controladas | Homologada; não deverá duplicar retentativas da plataforma |
pytest |
Testes automatizados | Homologada como ferramenta de referência |
pytest-cov e coverage |
Medição de cobertura | Homologadas conforme as metas da esteira |
ruff |
Formatação e análise estática | Homologada; configuração deverá ser versionada |
mypy |
Verificação estática de tipos | Homologada para o código de produção |
bandit |
Análise de segurança do código | Homologada para execução na esteira |
pip-audit |
Auditoria de dependências | Homologada para execução na esteira |
pre-commit |
Verificações locais antes do commit | Homologada; não substitui a esteira DevSecOps |
| Biblioteca | Finalidade | Situação e condições |
|---|---|---|
selenium |
Automação de navegadores | Homologada; controlar versões do navegador e do driver |
playwright |
Automação de navegadores | Homologada; controlar navegadores instalados e artefatos baixados |
robotframework |
Definição e execução de automações | Homologada exclusivamente para RPA e testes automatizados |
PyAutoGUI |
Automação de interface desktop | Homologada com condicionantes de sistema operacional, sessão gráfica e segurança |
beautifulsoup4 |
Leitura e extração de HTML | Homologada para fontes autorizadas; não contornar APIs ou controles de acesso |
lxml |
Processamento de XML e HTML | Homologada; validar conteúdo externo e utilizar parser seguro |
openpyxl |
Leitura e escrita de arquivos XLSX | Homologada; validar arquivos recebidos |
Pillow |
Processamento de imagens | Homologada para automação visual e tratamento de evidências |
| Biblioteca | Finalidade | Situação e condições |
|---|---|---|
pandas |
Processamento tabular | Homologada; avaliar memória e volume |
polars |
Processamento tabular | Homologada como alternativa ao pandas |
numpy |
Computação numérica | Homologada para ETL e IA |
pyarrow |
Formatos colunares e interoperabilidade | Homologada; validar esquema e compatibilidade |
SQLAlchemy |
Conexão e acesso controlado a dados | Homologada somente para ETL e fontes autorizadas; não homologa persistência de back-end |
openpyxl |
Processamento de planilhas | Homologada; aplicar validação de entrada |
psycopg |
Acesso a PostgreSQL | Homologada com condicionante de banco e conectividade aprovados |
oracledb |
Acesso a Oracle | Homologada com condicionante de banco e conectividade aprovados |
pyodbc |
Acesso via ODBC | Homologada com condicionantes de driver, banco e conectividade aprovados |
pyspark, dask, apache-beam e bibliotecas semelhantes dependem da
existência de plataforma ou orquestrador aprovado. A instalação isolada da
biblioteca não autoriza a criação de serviço permanente ou plataforma de
processamento distribuído.
| Biblioteca | Finalidade | Situação e condições |
|---|---|---|
numpy |
Computação numérica | Homologada |
pandas |
Preparação e análise de dados | Homologada; datasets não deverão ser armazenados no repositório |
scipy |
Computação científica | Homologada |
scikit-learn |
Aprendizado de máquina | Homologada para treinamento, avaliação e inferência autorizada |
torch |
Aprendizado profundo com PyTorch | Homologada com condicionantes de runtime, aceleradores e imagem-base |
tensorflow e keras |
Aprendizado profundo | Homologadas com condicionantes de runtime, aceleradores e imagem-base |
transformers |
Modelos e pipelines de linguagem ou visão | Homologada com análise da origem, licença, modelo e dados tratados |
xgboost e lightgbm |
Modelos de gradient boosting | Homologadas com validação das dependências nativas e do ambiente |
opencv-python |
Visão computacional | Homologada com validação do ambiente e dos dados utilizados |
Pillow |
Processamento de imagens | Homologada; aplicar proteção aos dados de entrada |
matplotlib e seaborn |
Visualização e avaliação | Homologadas; não constituem biblioteca de interface de aplicação |
joblib |
Persistência e processamento auxiliar | Homologada somente para artefatos de origem confiável |
jupyter |
Exploração e experimentação | Homologada; notebooks não serão o único artefato de produção |
Plataformas de ciclo de vida de modelos, como MLflow, e SDKs de IA generativa
dependem de homologação da plataforma, do serviço ou do modelo utilizado. A
biblioteca cliente, isoladamente, não autoriza transmissão de dados para
serviços externos nem adoção de novo provedor.
| Biblioteca | Finalidade | Situação e condições |
|---|---|---|
| SDK oficial da plataforma | Eventos e serviços da plataforma | Homologado com condicionante de plataforma aprovada |
boto3 |
SDK dos serviços AWS | Homologada somente em ambiente AWS aprovado |
aws-lambda-powertools |
Logs, métricas, tracing e idempotência | Homologada quando aderente ao padrão de observabilidade da plataforma |
pydantic |
Validação de eventos e configuração | Homologada; não autoriza API ou serviço web |
A menção a SDK de provedor não elimina os requisitos de portabilidade nem
autoriza acoplamento desnecessário a recursos proprietários.
Uma biblioteca não listada nesta página não está automaticamente proibida. Sua
adoção deverá ser registrada e tecnicamente justificada no projeto, atendendo
aos critérios de manutenção, segurança, licença, compatibilidade, integridade e
necessidade definidos nesta página.
Bibliotecas utilitárias de baixo risco poderão ser adotadas sem autorização
específica quando:
A autorização prévia da COATIC será obrigatória quando a biblioteca:
A COATIC poderá exigir análise prévia em outras situações, conforme o risco e o
impacto da dependência.
O catálogo deverá ser revisto quando houver mudança da linha LTS, alteração
relevante de licença, encerramento da manutenção, vulnerabilidade impeditiva ou
substituição da biblioteca por padrão institucional mais adequado.
| Cenário | Enquadramento |
|---|---|
| Robô que consulta sistemas e preenche formulários | Autorizado no contexto de RPA |
| Rotina agendada de extração, transformação e carga | Autorizado no contexto de ETL |
| Pipeline para treinamento ou execução em lote de modelo | Autorizado no contexto de IA |
| Função serverless que valida e transforma arquivo recebido | Autorizado no contexto serverless |
| Função serverless que processa evento de uma automação | Autorizado no contexto serverless |
| API de negócio desenvolvida com FastAPI | Não autorizada como padrão |
| Microsserviço Python executado em contêiner ou Kubernetes | Não autorizado como padrão |
| API Python publicada em AWS Lambda | Não autorizada como padrão; serverless não altera sua natureza de back-end |
| Aplicação web desenvolvida com Django ou Flask | Não autorizada como padrão |
| Interface de usuário construída com tecnologia Python | Não autorizada como padrão |
pyproject.toml e o arquivo de dependências resolvidas estão atualizados.