Proton v5

Proton Cloud SDK para Python

Pacote protoncloud-sdk no PyPI, para Python 3.10 ou superior. O nome de import é proton.

Instalação

pip install protoncloud-sdk

Ou, com uv:

uv add protoncloud-sdk

Configuração

Endereço e token são resolvidos nesta ordem:

Variável de ambiente: PROTON_HOST e PROTON_TOKEN.
proton.ini no diretório de execução.

Pelo runner, o PROTON_HOST e o id da execução (idDatasetRun) chegam prontos. O token vem da variável PROTON_TOKEN da máquina do runner ou do proton.ini:

[server]
hostname = https://app.protoncloud.com.br/api
token = <token>

O token pode vir com ou sem o prefixo Bearer . Deixe o proton.ini com o token fora do controle de versão.

Para apontar o projeto a outro servidor e ignorar o que o runner injeta, use config_precedence = file na seção [server]. Sem isso, quando o valor injetado difere do arquivo, a SDK imprime uma linha dizendo qual venceu (o token nunca é impresso).

O ciclo de uma execução

O runner chama uv run pytest tests/test_proton_script.py::test_run_proton_execution --id_dataset_run=<id>. A função percorre os passos do dataset: pergunta qual componente vem agora, abre o passo, executa o código do componente e fecha o passo. Um exemplo simplificado:

from proton.proton_automation import (
    end_component,
    get_current_component_name,
    start_component,
    update_run_status,
)
from proton.proton_logs import set_error_log, set_log_from_exception
from proton.run_status import RunStatus

from components import COMPONENTES  # nome do componente -> função com o código dele


def test_run_proton_execution(id_dataset_run):
    update_run_status(RunStatus.RUNNING)

    try:
        while nome := get_current_component_name():
            start_component()       # abre o passo e lê o ambiente da execução
            COMPONENTES[nome]()
            end_component()         # fecha o passo como Passed

        update_run_status(RunStatus.PASSED)
    except Exception as erro:
        set_log_from_exception(erro)
        set_error_log(str(erro))
        update_run_status(RunStatus.FAILED)
        raise

A fixture id_dataset_run lê a opção --id_dataset_run e chama set_id_dataset_run() (de proton.proton_env). Sem a opção, a SDK fica inerte e o teste roda localmente.

Dentro de um componente

from proton.proton_environment import get_environment_value
from proton.proton_files_and_resources import upload_image
from proton.proton_logs import set_log
from proton.proton_parameter import get_proton_value, set_proton_value


def criar_pedido():
    cliente = get_proton_value("CLIENTE")           # parâmetro do dataset
    url = get_environment_value("SISTEMA_URL")      # variável do ambiente da execução

    set_log(f"Criando pedido para {cliente}")
    # ... automação ...
    upload_image("evidencias/pedido.png")          # evidência do passo
    set_proton_value("NUMERO_PEDIDO", "4500012345")  # parâmetro de saída

Referência

Módulo	Função	O que faz
`proton.proton_automation`	`start_component()`	Abre o passo corrente e lê o ambiente da execução
	`end_component()`	Fecha o passo corrente
	`get_current_component_name()`	Nome do componente da vez; vazio quando não há mais passos
	`get_current_component_system()`	Sistema do componente da vez
	`update_run_status(status)`	Marca a execução com um `RunStatus`
	`get_dataset_run_info()`	Dados da execução
`proton.proton_parameter`	`get_proton_value(nome)`	Valor de um parâmetro do dataset no passo aberto
	`get_proton_all_component_parameters()`	Todos os parâmetros do passo aberto
	`set_proton_value(nome, valor)`	Grava um parâmetro de saída
	`get_proton_output_parameter_list(nome)`	Saídas gravadas na execução com esse nome
`proton.proton_logs`	`set_log(texto, disable_date_time=False)`	Escreve no log da execução; com `True`, aceita Markdown sem data e hora
	`set_log_from_exception(erro)`	Escreve o stack trace no log
	`set_error_log(texto)`	Registra o erro da execução
`proton.proton_files_and_resources`	`upload_image(caminho)`	Envia uma imagem como evidência
	`upload_file_resource(caminho)`	Envia um arquivo como evidência
`proton.proton_environment`	`get_environment_value(nome)` e outras	Ambiente da execução: ver Ambiente da execução
`proton.proton_env`	`is_proton_execution()`	Se a automação roda pelo Proton
	`get_id_dataset_run()` e `set_id_dataset_run(id)`	Id da execução

Status da execução

O Proton 5 aceita RunStatus.RUNNING, PASSED e FAILED. Os status do Proton 4 (FAILED_DATA, FAILED_ENVIRONMENT e IN_PROCESS) estão obsoletos: a SDK envia FAILED no lugar dos dois primeiros e RUNNING no lugar do último, com um DeprecationWarning e um aviso no log. Para separar falha de dados de falha de ambiente, registre o motivo no log.

Erros de comunicação

Um erro do servidor não interrompe a automação: a leitura volta vazia (get_proton_value devolve "" também quando o parâmetro não existe) e as chamadas de controle imprimem uma linha [proton] com a rota e o status HTTP, que o runner leva para o log da execução. Quando um valor vier vazio sem motivo, comece pelo log.

A exceção é o ambiente da execução: ler uma variável que não existe para o script com ProtonEnvironmentError, porque seguir com um valor vazio esconderia o problema.

Instalação​

Configuração​

O ciclo de uma execução​

Dentro de um componente​

Referência​

Status da execução​

Erros de comunicação​