Metadata-Version: 2.5
Name: protoncloud-sdk
Version: 5.0.0
Summary: Cliente Python da plataforma Proton: execução de automações, logs, parâmetros e recursos.
Project-URL: Homepage, https://protoncloud.com.br
Author: Atomic Solutions
License: Proprietary
License-File: LICENSE
Keywords: automation,proton,qa,rpa,testing
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: requests>=2.31
Description-Content-Type: text/markdown

# Proton Lib (Python)

Cliente Python da plataforma [Proton](https://protoncloud.com.br). A automação usa
esta biblioteca para reportar ao Proton o progresso, o status, os logs, os
parâmetros e os recursos de cada execução.

Distribuição: `protoncloud-sdk`. Import: `proton`.

```python
from proton.proton_automation import start_component, end_component, update_run_status
from proton.run_status import RunStatus
```

## Instalação

```bash
pip install protoncloud-sdk
```

ou, com [uv](https://docs.astral.sh/uv/):

```bash
uv add protoncloud-sdk
```

## Configuração

Host e token são resolvidos nesta ordem — a mesma convenção das bibliotecas Java
do Proton:

1. **Variável de ambiente** — `PROTON_HOST`, `PROTON_TOKEN`
2. **`proton.ini`** no diretório de execução

Quando a automação roda pelo Proton Runner, ele injeta `PROTON_HOST` e
`PROTON_TOKEN` no processo, apontando para o servidor de onde a execução nasceu.
É isso que permite o mesmo projeto rodar em qualquer ambiente sem editar arquivo
— e sem guardar token no repositório.

O arquivo continua válido e é a única fonte quando se roda a automação fora do
runner:

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

[reports]
video_record = false
video_upload = true
```

O token pode vir com ou sem o prefixo `Bearer `; a biblioteca normaliza e nunca
o duplica.

Não versione o `proton.ini` com o token preenchido: prefira deixá-lo fora do
controle de versão e deixar o runner fornecer as credenciais.

### Fixando o ambiente do projeto

Para um teste apontado a outro servidor, ou um projeto que precise ignorar o que
o runner injeta:

```ini
[server]
config_precedence = file
```

Sem isso, quando o valor injetado difere do arquivo, a biblioteca imprime uma
linha dizendo qual venceu. O valor do token nunca é impresso, porque a saída da
automação sobe como log da execução no Proton.

## Contexto da execução

| variável | origem | uso |
|---|---|---|
| `idDatasetRun` | runner | identifica a execução; sem ela a biblioteca fica inerte (`is_proton_execution()` é `False`) |
| `PROTON_HOST` | runner ou `proton.ini` | base da API |
| `PROTON_TOKEN` | runner ou `proton.ini` | autenticação |
| `idRunProgress` | definida pela própria biblioteca em `start_component()` | componente em andamento |

Fora de uma execução do Proton, `is_proton_execution()` é `False` e as chamadas
viram no-op — o mesmo teste roda localmente sem falar com o servidor.

## Migrando de uma cópia local da pasta `proton/`

Projetos que carregam esta biblioteca como uma pasta `proton/` copiada migram em
dois passos:

1. adicione `protoncloud-sdk` às dependências;
2. **apague a pasta `proton/` do projeto.**

O segundo passo não é opcional: a pasta local tem precedência sobre o pacote
instalado, e enquanto ela existir o projeto continua executando a cópia antiga.
