protoncloud-sdk 5.0.0__py3-none-any.whl

proton/proton_automation.py

@@ -0,0 +1,245 @@
+import os
+import requests
+from proton.proton_env import get_api_url, get_auth_header, get_host, get_id_dataset_run, is_proton_execution
+from proton.run_status import RunStatus
+
+
+def _get_dataset_run_url():
+    return get_api_url(f"dataset-run/{get_id_dataset_run()}")
+
+
+def _request_json(method, url, params=None, body=None):
+    if not is_proton_execution():
+        return {}
+
+    response = requests.request(method, url, params=params, json=body, headers=get_auth_header())
+
+    # O print vai para o stdout, que o runner envia como log da execucao no Proton.
+    if response.status_code != 200:
+        print(f"[proton] {method} {response.url} -> HTTP {response.status_code}: {response.text[:300]}")
+        return {}
+
+    try:
+        return response.json()
+    except ValueError:
+        print(f"[proton] {method} {response.url} -> HTTP 200 sem JSON valido: {response.text[:120]!r}")
+        return {}
+
+
+def _get_dataset_run_param(service, response_key):
+    data = _request_json("GET", f"{_get_dataset_run_url()}/{service}")
+    return data.get(response_key, "")
+
+
+def start_component():
+    """Inicia um componente."""
+    if is_proton_execution():
+        data = _request_json("PUT", f"{_get_dataset_run_url()}/start-component")
+
+        if data:
+            run_progress_id = data.get("id") or data.get("idRunProgress")
+            if run_progress_id is not None:
+                os.environ["idRunProgress"] = str(run_progress_id)
+
+        return data
+
+    return {}
+
+def end_component():
+    """Finaliza um componente."""
+
+    if is_proton_execution():
+        data = _request_json("PUT", f"{_get_dataset_run_url()}/end-component")
+        os.environ.pop('idRunProgress', None)
+
+        if data:
+            return data.get("returnType", data.get("runType", ""))
+
+    return ""
+
+def update_run_status(status:RunStatus):
+    """Atualiza o status de execução de um cenário."""
+    if is_proton_execution():
+        status_value = status.value if isinstance(status, RunStatus) else str(status)
+        _request_json("PUT", f"{_get_dataset_run_url()}/update-status", body={"status": status_value})
+
+def get_current_component_system():
+    """
+    Retorna o tipo de sistema do componente corrente.
+
+    Retorna:
+        str: Tipo de sistema do componente. String vazia se não encontrado ou em caso de erro.
+    """
+    return _get_dataset_run_param("component-system", "system")
+
+def get_current_component_name():
+    """
+    Retorna o nome do componente corrente.
+
+    Retorna:
+        str: Nome do componente. String vazia se não encontrado ou em caso de erro.
+    """
+    return _get_dataset_run_param("component-name", "name")
+
+def get_scenario_reference():
+    """
+    Retorna o texto do campo de Referência do cenário
+
+    Retorna:
+        str: Referência do cenário. String vazia se a referência não for encontrada ou ocorrer algum erro.
+    """
+    return _get_dataset_run_param("automation-reference", "reference")
+
+
+
+def get_cycle_name():
+    """Retorna o nome do ciclo."""
+    return _get_dataset_run_param("cycle", "cycle")
+
+def get_dataset_run_info():
+    """Retorna informações do Dataset Run em formato JSON."""
+    return _request_json("GET", _get_dataset_run_url())
+
+def get_dataset_run_components():
+    """Retorna informações do Dataset Run em formato JSON."""
+    data = _request_json(
+        "GET",
+        get_api_url("dataset-run"),
+        params={
+            "componentsByDatasetRun": "true",
+            "idDatasetRun": get_id_dataset_run(),
+        },
+    )
+
+    return data if data else get_dataset_run_info()
+
+def get_dataset_run_component_names():
+    """
+    Retorna uma lista com os nomes de todos os componentes do Dataset Run.
+    
+    Retorna:
+        list[str]: Lista com os nomes dos componentes.
+    """
+    dataset_run_info = get_dataset_run_components()
+    
+    # Verifica se o retorno contém a chave 'datasetScenario' e 'datasetComponent'
+    components = []
+
+    if "datasetScenario" in dataset_run_info and "datasetComponent" in dataset_run_info["datasetScenario"]:
+        components = dataset_run_info["datasetScenario"]["datasetComponent"]
+    elif "dataset" in dataset_run_info and "datasetComponent" in dataset_run_info["dataset"]:
+        components = dataset_run_info["dataset"]["datasetComponent"]
+    elif "datasetComponent" in dataset_run_info:
+        components = dataset_run_info["datasetComponent"]
+    elif "components" in dataset_run_info:
+        components = dataset_run_info["components"]
+
+    if components:
+        sorted_components = sorted(components, key=lambda x: x.get("componentOrder", 0))
+        
+        component_names = [
+            comp.get("component", {}).get("name", comp.get("name", ""))
+            for comp in sorted_components 
+            if comp.get("component") or comp.get("name")
+        ]
+        return component_names
+    
+    return []
+
+
+
+def get_dataset_scenario_by_dataset_run():
+    """Retorna o ID do Dataset Scenario a partir do ID do Dataset Run."""
+    execution_info = get_dataset_run_info()
+    return execution_info.get("idDataset", execution_info.get("idDatasetScenario", execution_info.get("Id_Dataset_Scenario", "")))
+
+def get_dataset_scenario_info(dataset_scenario_id):
+    """Retorna informações do dataset Scenario em formato JSON."""
+    dataset_info = _request_json("GET", f"{get_host()}/dataset/{dataset_scenario_id}")
+    if dataset_info:
+        return dataset_info
+
+    return _request_json("GET", f"{get_host()}/dataset-scenario/{dataset_scenario_id}")
+
+def get_execution_client():
+    """Retorna informações de onde a automação foi disparada em formato JSON."""
+    informacoes_execucao = get_dataset_run_info()
+    client_id = informacoes_execucao.get('idClient')
+
+    if not client_id:
+        return {}
+
+    return _request_json("GET", f"{get_host()}/client/{client_id}")
+
+def get_dataset_category():
+    """Retorna as informações da categoria atribuída ao dataset."""
+    dataset_id = get_dataset_scenario_by_dataset_run()
+    dataset_info = get_dataset_scenario_info(dataset_id) if dataset_id else {}
+
+    if dataset_info:
+        return dataset_info
+
+    execution_info = get_dataset_run_info()
+    category_id = execution_info.get("datasetScenario", {}).get("idCategory")
+
+    if not category_id:
+        return {}
+
+    return _request_json("GET", f"{get_host()}/category/{category_id}")
+
+def get_dataset_category_name():
+    """Retorna o nome da categoria do dataset definido no Proton."""
+    dataset_category_infos = get_dataset_category()
+    return dataset_category_infos.get("category") or dataset_category_infos.get("name", "")
+
+def get_dataset_system():
+    """Retorna o campo 'System' do dataset definido no Proton."""
+    dataset_scenario_id = get_dataset_scenario_by_dataset_run()
+    scenario_info = get_dataset_scenario_info(dataset_scenario_id)
+    return scenario_info.get("system", "")
+
+def get_component_types():
+    """
+    Retorna os tipos de componentes presentes no Dataset Run.
+
+    Retorna:
+        str: Uma string com os tipos de componentes separados por ponto e vírgula (;), 
+             ou uma string vazia em caso de erro.
+    """
+    data = _request_json("GET", _get_dataset_run_url(), params={"componentTypes": "true"})
+
+    if isinstance(data, list):
+        component_types = [item.get("Type") for item in data if item.get("Type")]
+        return ";".join(component_types)
+    
+    return "" 
+
+def get_dataset_run_parameters():
+    """Retorna os parâmetros do Dataset Run em formato JSON."""
+    return _request_json(
+        "GET",
+        get_api_url("dataset-run-parameter"),
+        params={
+            "idDatasetRun": get_id_dataset_run(),
+            "organized": "true",
+        },
+    )
+
+def get_mobile_app(mobile_app_id):
+    """Retorna informações sobre a aplicação mobile em formato JSON."""
+    return _request_json("GET", get_api_url(f"mobile-app/{mobile_app_id}"))
+    
+def get_scenario_name_by_dataset_run():
+    """
+    Retorna o nome do cenário a partir do Dataset Run ID.
+
+    Retorna:
+        str: Nome do cenário. Uma string vazia caso o nome não seja encontrado ou ocorra um erro. 
+    """
+
+    scenario_name = _get_dataset_run_param("automation-name", "name")
+    if scenario_name:
+        return scenario_name
+
+    data = _request_json("GET", _get_dataset_run_url(), params={"scenarioNameByDatasetRun": "true"})
+    return data.get("Name", "")

proton/proton_client_parama.py

@@ -0,0 +1,59 @@
+from enum import Enum
+import os
+
+class ProtonClientParam(Enum):
+    @classmethod
+    def _root_folder(cls):
+        return os.path.expanduser("~")
+
+    @classmethod
+    def _proton_client_folder(cls):
+        return cls._root_folder() + os.sep + ".proton-client"
+
+    @classmethod
+    def _config_folder(cls):
+        return cls._proton_client_folder() + os.sep + "config"
+
+    @classmethod
+    def _scripts_folder(cls):
+        return cls._proton_client_folder() + os.sep + "scripts"
+
+    @classmethod
+    def _components_folder(cls):
+        return cls._proton_client_folder() + os.sep + "components"
+
+    @classmethod
+    def _library_folder(cls):
+        return cls._proton_client_folder() + os.sep + "library"
+
+    @classmethod
+    def _drivers_folder(cls):
+        return cls._proton_client_folder() + os.sep + "drivers"
+
+    @classmethod
+    def _screenshots_folder(cls):
+        return cls._proton_client_folder() + os.sep + "screenshots"
+
+    @classmethod
+    def _video_folder(cls):
+        return cls._proton_client_folder() + os.sep + "video"
+
+    @classmethod
+    def _log_folder(cls):
+        return cls._proton_client_folder() + os.sep + "log"
+
+    @classmethod
+    def _repository_folder(cls):
+        return cls._root_folder() + os.sep + ".proton-client-repo"
+
+    @classmethod
+    def _attachments_folder(cls):
+        return cls._proton_client_folder() + os.sep + "attachments"
+
+    @classmethod
+    def _cmd_folder(cls):
+        return cls._proton_client_folder() + os.sep + "cmd"
+
+    @classmethod
+    def _app_folder(cls):
+        return cls._proton_client_folder() + os.sep + "app"

proton/proton_env.py

@@ -0,0 +1,187 @@
+from configparser import ConfigParser
+import os
+
+
+def _is_localhost(host):
+    """Retorna True quando o host aponta para a máquina local."""
+    return any(local_address in host for local_address in ("localhost", "127.0.0.1", "::1", "[::1]"))
+
+def get_proton_config():
+    """
+    Lê e retorna a configuração do arquivo `proton.ini`.
+
+    Returns:
+        ConfigParser: Objeto ConfigParser contendo as configurações do arquivo `proton.ini`.
+    """
+    config = ConfigParser()
+    config.read('proton.ini')
+    return config
+
+
+_logged_overrides = set()
+
+
+def _from_file(option, section='server'):
+    """Valor de uma chave do `proton.ini`, ou string vazia se o arquivo/chave não existir."""
+    return get_proton_config().get(section, option, fallback='').strip()
+
+
+def _file_precedence():
+    """
+    `[server] config_precedence = file` faz o arquivo do projeto vencer o que o runner
+    injeta. Serve para teste apontado a outro ambiente e para projetos legados que
+    precisam continuar falando com o servidor fixado no repositório.
+    """
+    return _from_file('config_precedence').lower() == 'file'
+
+
+def _resolve(env_key, option, sensitive=False):
+    """
+    Resolve uma configuração com a prioridade ambiente -> `proton.ini`.
+
+    O runner injeta `PROTON_HOST` e `PROTON_TOKEN` no processo da automação, para que a
+    execução reporte ao servidor de onde ela nasceu — um `proton.ini` apontando para outro
+    ambiente faz a execução reportar no lugar errado, e como o componente nunca avança lá,
+    o runner relança a automação indefinidamente.
+
+    Mesma convenção de nomes do atomic-framework: a chave `proton.host` vira `PROTON_HOST`.
+    """
+    file_value = _from_file(option)
+
+    if _file_precedence() and file_value:
+        return file_value
+
+    runtime_value = (os.getenv(env_key) or '').strip()
+
+    if not runtime_value:
+        return file_value
+
+    if file_value and file_value != runtime_value and env_key not in _logged_overrides:
+        # Sobrescrita silenciosa vira depuração às cegas. O valor sensível nunca é
+        # impresso: o stdout da automação sobe como log da execução no Proton.
+        _logged_overrides.add(env_key)
+        if sensitive:
+            print(f'[proton] {env_key} definido em tempo de execução (valor do arquivo ignorado)')
+        else:
+            print(f'[proton] {env_key} definido em tempo de execução: {runtime_value} '
+                  f'(arquivo declarava: {file_value})')
+
+    return runtime_value
+
+
+def get_host():
+    """
+    Obtém o host do Proton: `PROTON_HOST` do ambiente, com o `proton.ini` como fallback.
+
+    Returns:
+        str: Host da API do Proton, sempre com protocolo.
+    """
+    host = _resolve('PROTON_HOST', 'hostname')
+
+    if not host:
+        raise RuntimeError(
+            'Host do Proton não configurado: defina PROTON_HOST no ambiente '
+            'ou a chave hostname na seção [server] do proton.ini'
+        )
+
+    if _is_localhost(host) or host.startswith('https://'):
+        return host
+
+    if host.startswith('http://'):
+        return f"https://{host[len('http://'):] }"
+
+    return f"https://{host}"
+
+def get_token():
+    """
+    Obtém o token do Proton: `PROTON_TOKEN` do ambiente, com o `proton.ini` como fallback.
+
+    Returns:
+        str: Token de acesso, ou string vazia quando não há nenhum configurado.
+    """
+    return _resolve('PROTON_TOKEN', 'token', sensitive=True)
+
+def is_record_video():
+    """
+    Verifica se a gravação de vídeo está habilitada para os relatórios.
+
+    Returns:
+        bool: `True` se `video_record` estiver configurado como 'true' na seção `[reports]` do arquivo `proton.ini`, caso contrário `False`.
+    """
+    config = get_proton_config()
+    video_record = config.get('reports', 'video_record', fallback='false').lower()
+    return video_record == 'true'
+
+def get_api_url(path):
+    """
+    Monta a URL completa de um recurso da API a partir do hostname do `proton.ini`.
+
+    Não usa `urllib.parse.urljoin`: com um caminho iniciado por '/', o urljoin descarta o
+    prefixo '/api' do hostname e a requisição cai na página do frontend (HTML, status 200).
+
+    Args:
+        path (str): Caminho do recurso, com ou sem a barra inicial (ex.: 'dataset-run/10').
+
+    Returns:
+        str: URL absoluta do recurso.
+    """
+    return f"{get_host().rstrip('/')}/{str(path).lstrip('/')}"
+
+def get_auth_header():
+    """
+    Gera o cabeçalho de autenticação para requisições HTTP, baseado no token do Proton.
+
+    Aceita o token do `proton.ini` com ou sem o prefixo 'Bearer ' e nunca o duplica:
+    'Bearer Bearer <token>' é recusado pelo Proton 5 com 401.
+
+    Returns:
+        dict: Dicionário com o cabeçalho de autenticação no formato {'Authorization': 'Bearer token'}.
+    """
+    token = (get_token() or '').strip()
+
+    if not token:
+        return {}
+
+    if token.lower().startswith('bearer '):
+        token = token[len('bearer '):].strip()
+
+    return {'Authorization': f'Bearer {token}'}
+
+def get_id_dataset_run():
+    """
+    Obtém o ID do Dataset Run, que representa o número de execução do cenário no Proton.
+
+    Returns:
+        str: Valor do ID Dataset Run configurado nas variáveis de ambiente.
+             Retorna None se a variável `idDatasetRun` não estiver definida.
+    """
+    return os.getenv('idDatasetRun')
+
+def get_idRunProgress():
+    """
+    Obtém o ID do progresso de execução (Run Progress) no Proton.
+
+    Returns:
+        str: Valor do ID Run Progress configurado nas variáveis de ambiente.
+             Retorna None se a variável `Id_Run_Progress` não estiver definida.
+    """
+    return os.getenv('idRunProgress')
+
+def is_proton_execution():
+    """
+    Verifica se a execução está sendo realizada no Proton.
+
+    Returns:
+        bool: Retorna True se a variável de ambiente `idDatasetRun` estiver definida,
+              indicando execução no Proton. Caso contrário, retorna False.
+    """
+    return os.getenv('idDatasetRun') is not None
+
+def set_id_dataset_run(id_dataset_run):
+    """
+    Define o valor do ID Dataset Run (ID de execução do cenário) como uma variável de ambiente.
+
+    Args:
+        id_dataset_run (str): Valor do ID Dataset Run a ser configurado.
+    """
+    os.environ["idDatasetRun"] = id_dataset_run

proton/proton_files_and_resources.py

@@ -0,0 +1,170 @@
+
+import os
+
+import requests
+from proton.proton_client_parama import ProtonClientParam
+from proton.proton_env import get_api_url, get_auth_header, get_host, get_id_dataset_run, get_idRunProgress, is_proton_execution
+from proton.proton_logs import set_log
+
+BUFFER_SIZE = 102400
+ENTITY_RUN_PROGRESS = "run_progress"
+ENTITY_DATASET_RUN_RESOURCE = "dataset_run_resource"
+
+def upload_file_resource(file_resource):
+    """Realiza o upload de um arquivo como recurso no Proton."""
+    try:
+        file_name = os.path.basename(file_resource)
+        file_path = os.path.dirname(file_resource)
+        json_response = insert_proton_file(ENTITY_DATASET_RUN_RESOURCE, get_id_dataset_run(), file_path, file_name)
+        return json_response
+    except Exception as e:
+        set_log(f"Erro ao fazer upload do arquivo: {e}")
+        return {}  # Retorna um dicionário vazio em caso de falha 
+
+def upload_image(full_image_path):
+    """Realiza upload de uma imagem para o Proton."""
+    try:
+        image_name = os.path.basename(full_image_path)
+        image_path = os.path.dirname(full_image_path)  
+        return insert_proton_file(ENTITY_RUN_PROGRESS, get_idRunProgress(), image_path, image_name)
+    except Exception as e:
+        set_log(f"Erro ao fazer upload da imagem: {e}")
+        return {}
+
+def insert_proton_file(entity, entity_id, file_path, file_name):
+    """Lógica central de upload de arquivos. Requer uma implementação da função de upload."""
+    if is_proton_execution():
+        url = get_host() + f"/file-system/upload?entity={entity}&idEntity={entity_id}"
+        return file_upload(url, file_path, file_name)
+
+    return {}
+
+
+def file_upload(url_path, file_path, file_name):
+    """Realiza upload de arquivos, retornando a resposta JSON do Proton.
+
+    Args:
+        url_path (str): A URL para onde o arquivo será enviado.
+        file_path (str):  O caminho da pasta contendo o arquivo.
+        file_name (str): O nome do arquivo. 
+
+    Retorna:
+        dict: Dicionário Python contendo a resposta JSON do Proton, ou um dicionário vazio
+              caso ocorra algum erro. 
+    """
+    try:
+        with open(os.path.normpath(os.path.join(file_path, file_name)), 'rb') as file_data:
+            files = {
+                "file": (file_name, file_data)
+            }
+
+            response = requests.post(url_path, headers=get_auth_header(), files=files)
+
+            if response.status_code != 200:
+                set_log(f"Erro ao fazer upload do arquivo. Código de status: {response.status_code}")
+                return {}
+            
+            return response.json() if response.content else {}
+
+    except ValueError:
+        set_log(f"Erro ao decodificar a resposta do upload do arquivo: {file_name}")
+
+    except Exception as e:
+        set_log(f"Erro durante o upload do arquivo: {e}")
+
+    return {}
+
+def get_mobile_app(mobile_app_id):
+    """Retorna informações sobre a aplicação mobile em formato JSON."""
+    url = get_api_url(f"mobile-app/{mobile_app_id}")
+    header = get_auth_header()
+
+    response = requests.get(url, headers=header)
+
+    if response.status_code == 200:
+        return response.json()
+    else:
+        return {}
+
+def get_signed_url_file(entity, entity_id):
+    """Retorna a URL assinada para um arquivo."""
+    url = get_api_url("file-system")
+    header = get_auth_header()
+
+    params = {
+        "entity": entity,
+        "idEntity": entity_id
+    }
+
+    response = requests.get(url, params=params, headers=header)
+
+    if response.status_code == 200:
+        return response.json()
+    else:
+        return {}
+
+def download_mobile_app(entity_id):
+    """Baixa uma aplicação mobile e retorna o caminho para o arquivo."""
+    json_file = get_signed_url_file("Mobile_App", entity_id)
+
+    try:
+        file_name = json_file.get("fileName", "")
+        app_file_path = ProtonClientParam._app_folder() + os.sep
+
+        os.makedirs(app_file_path, exist_ok=True)  # Cria a pasta se não existir
+        execute_download_file(json_file.get("url", ""), file_name, app_file_path)
+        return os.path.join(app_file_path, file_name)
+
+    except KeyError as e:
+        print(f"Erro ao obter informações de download: {e}")
+        return ""
+
+def execute_download_file(file_url, file_name, save_dir):
+    """Realiza o download de um arquivo."""
+    try:
+        response = requests.get(file_url, stream=True) 
+        response.raise_for_status()  # Lança exceção em caso de código de erro
+
+        save_file_path = os.path.join(save_dir, file_name)
+        with open(save_file_path, 'wb') as f:
+            for chunk in response.iter_content(chunk_size=BUFFER_SIZE):
+                f.write(chunk)
+
+        set_log("Arquivo " + file_name + " baixado!")
+
+    except requests.exceptions.RequestException as e:
+        set_log(f"Erro ao baixar arquivo: {e}")
+
+def get_component_file_id(component_id):
+    """Retorna informações sobre o arquivo anexado no componente."""
+    url = get_api_url("file")
+    header = get_auth_header()
+
+    params = {
+        "componentFile": "true",
+        "Id_Component": component_id
+    }
+
+    response = requests.get(url, params=params, headers=header)
+
+    if response.status_code == 200:
+        return response.text  # Retornando texto diretamente (assumindo que o formato se mantém)
+    else:
+        return ""
+
+def get_test_script_scenario_file_id(dataset_run_id):
+    """Retorna informações do arquivo de script de teste associado a um dataset run."""
+    url = get_api_url("file")
+    header = get_auth_header()
+
+    params = {
+        "testScriptScenarioFileByDatasetRun": "true",
+        "idDatasetRun": dataset_run_id
+    }
+
+    response = requests.get(url, params=params, headers=header)
+
+    if response.status_code == 200:
+        return response.text
+    else:
+        return ""  

proton/proton_git.py

@@ -0,0 +1,89 @@
+import os
+import subprocess
+import threading
+
+import requests
+from proton.proton_client_parama import ProtonClientParam
+from proton.proton_env import get_api_url, get_auth_header
+from proton.proton_logs import set_log
+
+
+def get_remote_repository(system_type):
+    """Obtém informações sobre um repositório remoto."""
+    url = get_api_url("git-repository")
+    header = get_auth_header()
+
+    params = {
+        "selectRemoteRepository": "true",
+        "System": system_type
+    }
+
+    response = requests.get(url, params=params, headers=header)
+
+    if response.status_code == 200:
+        return response.json()
+    else:
+        return None  
+
+def get_remote_repository_legacy(system_type):
+    """Obtém informações sobre um repositório remoto (versão legacy)."""
+    url = get_api_url("git-repository")
+    header = get_auth_header()
+
+    params = {
+        "selectRemoteRepository": "true",
+        "Type": system_type
+    }
+
+    response = requests.get(url, params=params, headers=header)
+
+    if response.status_code == 200:
+        return response.json()
+    else:
+        return None 
+
+def get_remote_header_hash(remote_authorization, repository, branch):
+    """Obtém o hash do cabeçalho de um repositório remoto."""
+    url = get_api_url("git-repository")
+    header = get_auth_header()
+
+    params = {
+        "selectRemoteHeaderHash": "true",
+        "Remote_Authorization": remote_authorization,
+        "Repository": repository,
+        "Branch": branch
+    }
+
+    response = requests.get(url, params=params, headers=header)
+
+    if response.status_code == 200:
+        data = response.json()
+        return data.get("sha", "")
+    else:
+        return ""
+
+def clone_repository(owner_repo, branch, commit_hash, authorization):
+    """Clona um repositório Git."""
+    repo_folder = os.path.join(ProtonClientParam._repository_folder(), owner_repo, branch, commit_hash)
+    os.makedirs(repo_folder, exist_ok=True)
+
+    def run_git_clone(repo_folder, branch, authorization, owner_repo):
+        try:
+            url = f"https://{authorization}@github.com/{owner_repo}.git"
+            subprocess.run(
+                ["git", "clone", "--branch", branch, url], 
+                cwd=repo_folder,
+                check=True,  # Levanta exceção se o git retornar código de erro
+                capture_output=True,   # Captura o output 
+                text=True  
+            )
+        except subprocess.CalledProcessError as e:
+            set_log(f"Erro ao clonar: {e.output}") 
+
+    thread = threading.Thread(target=run_git_clone, args=(repo_folder, branch, authorization, owner_repo))
+    thread.start()
+
+def get_local_repository_path(owner_repo, repository, branch, commit_hash):
+    """Retorna o caminho para um repositório local."""
+    repo_folder = os.path.join(ProtonClientParam._repository_folder(), owner_repo, branch, commit_hash, repository)
+    return repo_folder

proton/proton_logs.py

@@ -0,0 +1,53 @@
+import traceback
+
+import requests
+
+from proton.proton_env import get_auth_header, get_host, get_id_dataset_run, is_proton_execution
+
+
+def set_log(log_message, disable_date_time=False):
+    """Envia uma entrada de log"""
+
+    if is_proton_execution():
+        dataset_run_id = get_id_dataset_run()
+
+        if dataset_run_id is not None:
+            url = f"{get_host()}/dataset-run-log/{dataset_run_id}"
+
+            body = {
+                "idDatasetRun": dataset_run_id,
+                "log": log_message,
+                "disableDateTime": disable_date_time,
+            }
+
+            return requests.put(url, json=body, headers=get_auth_header())
+    else:
+        print(log_message)
+
+    return None
+
+
+def set_error_log(error_message):
+    """Envia um log de erro estruturado para o Proton."""
+    if is_proton_execution():
+        dataset_run_id = get_id_dataset_run()
+
+        if dataset_run_id is not None:
+            url = f"{get_host()}/dataset-run/{dataset_run_id}/error"
+            body = {
+                "idDatasetRun": dataset_run_id,
+                "error": error_message,
+            }
+
+            return requests.put(url, json=body, headers=get_auth_header())
+    else:
+        print(error_message)
+
+    return None
+
+# ATENÇÃO -----------------
+def set_log_from_exception(e):
+    """Envia um log de exceção formatando o stack trace"""
+    stack_trace = "".join(traceback.format_exception(type(e), e, e.__traceback__))
+    for line in stack_trace.splitlines():
+        set_log(line)

proton/proton_parameter.py

@@ -0,0 +1,127 @@
+import requests
+from proton.proton_env import get_auth_header, get_host, get_id_dataset_run, is_proton_execution
+
+
+def _get_dataset_run_url():
+    return f"{get_host()}/dataset-run/{get_id_dataset_run()}"
+
+
+def set_proton_value(param, value):
+    """
+    Insere um valor de output (saída) no Proton.
+
+    Args:
+        param (str): O nome do parâmetro, deve ser idêntico ao nome definido no Proton.
+        value (str ou int): O valor a ser inserido no parâmetro de output.
+    """
+    if is_proton_execution():
+        params = {
+            "parameter": param
+        }
+        
+        params["value"] = str(value)
+
+        # Proton 5: a rota e "/set-value"; "/setValue" (Proton 4) responde 404 e o valor nunca era gravado.
+        response = requests.put(f"{_get_dataset_run_url()}/set-value", params=params, headers=get_auth_header())
+
+        if response.status_code != 200:
+            print(f"[proton] set_proton_value({param!r}) -> HTTP {response.status_code}: {response.text[:300]}")
+
+        return response.status_code
+
+def get_proton_value(param):
+    """Busca valor de parâmetro do Proton"""
+    if not is_proton_execution():
+        return ""
+
+    params = {
+        "parameter": param
+    }
+
+    response = requests.get(f"{_get_dataset_run_url()}/get-value", params=params, headers=get_auth_header())
+
+    if response.status_code == 200:
+        data = response.json()
+        
+        return data.get("value", "") if data.get("value", "") else ''
+    else:
+        return ""
+
+def get_proton_all_scenario_parameters():
+    """
+    Retorna todos os parâmetros de cenário do Proton.
+
+    Retorna:
+        dict: Um dicionário contendo todos os parâmetros de cenário.
+    """
+    host = get_host()
+    dataset_run_id = get_id_dataset_run()
+    header = get_auth_header()
+
+    url = f"{host}/dataset-run/get-all-params/{dataset_run_id}"
+
+    response = requests.get(url, headers=header)
+
+    if response.status_code == 200:
+        return response.json()  # Retorna os parâmetros de cenário em formato JSON
+    else:
+        return {}
+
+def get_proton_all_component_parameters():
+    """
+    Retorna todos os parâmetros de componente do Proton.
+
+    Retorna:
+        dict: Um dicionário contendo todos os parâmetros de componente.
+    """
+    host = get_host()
+    dataset_run_id = get_id_dataset_run()
+    header = get_auth_header()
+
+    url = f"{host}/dataset-run/get-component-params/{dataset_run_id}"
+
+    response = requests.get(url, headers=header)
+
+    if response.status_code == 200:
+        return response.json()  # Retorna os parâmetros de componente em formato JSON
+    else:
+        return {}
+
+def get_proton_output_parameter_list(output_parameter_name=None):
+    """
+    Retorna as ocorrências de um parâmetro de output (saída) específico ou 
+    de todos os parâmetros de output presentes na ID do Dataset Run.
+
+    Args:
+        output_parameter_name (str, opcional): Nome do parâmetro de output a ser filtrado.
+                                           Se não for fornecido, retorna todos os parâmetros.
+
+    Retorna:
+        list: Uma lista com as ocorrências dos parâmetros de output no formato JSON. 
+              Caso não encontre parâmetros ou ocorra algum erro, retorna uma lista vazia.
+    """
+
+    host = get_host()  # Lembre-se de definir a lógica para obter o 'host'
+    url = f"{host}/results-run"
+    header = get_auth_header()
+
+
+    params = {
+        "idDatasetRun": get_id_dataset_run()
+    }
+    if output_parameter_name:
+        params["parameter"] = output_parameter_name
+
+    response = requests.get(url, params=params, headers=header)
+
+    if response.status_code == 200:
+        return response.json()  # Assumindo que a resposta é em formato JSON
+    else:
+        return []  # Indica que não foram encontrados outputs ou houve erro
+
+# Versão sobrecarregada do método, chamando a função principal com output_parameter_name=""
+def get_proton_output_parameter_list_all():
+    """
+    Retorna as ocorrências de todos os parâmetros de output presentes na ID do Dataset Run.
+    """
+    return get_proton_output_parameter_list() 

proton/run_status.py

@@ -0,0 +1,9 @@
+from enum import Enum
+
+class RunStatus(Enum):
+    RUNNING = "Running"
+    PASSED = "Passed"
+    FAILED = "Failed"
+    FAILED_DATA = "Failed (Dados)"
+    FAILED_ENVIRONMENT = "Failed (Ambiente)"
+    IN_PROCESS = "In Process"

protoncloud_sdk-5.0.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+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.

protoncloud_sdk-5.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+proton/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proton/proton_automation.py,sha256=7QFahZuiEvqP_8054yE5Yb5ndwqY0xDSAVv6zlhhrZI,8366
+proton/proton_client_parama.py,sha256=4PDY3eUl9a_BfjACvAskmT5RU1D4fKhppN57Md3qS1E,1605
+proton/proton_env.py,sha256=0HyTV_Hi9Dp-I6w0EAwLyBg7FSVf_HOzzoDkPETu8SI,6296
+proton/proton_files_and_resources.py,sha256=sZnjLQ0UEh20ggCONS23xBMUq9xxkAMNVgRB8D3CtfI,5802
+proton/proton_git.py,sha256=RZr2iRmySlF4HIE450GFphwxlBctrLeD_eNgNf01H1E,2904
+proton/proton_logs.py,sha256=sbvjTyebUQYJ6OTQckjDDfbLtvLlAPoMEj9l3-zH2Tw,1511
+proton/proton_parameter.py,sha256=I3RflQBM4njYkEt38PHDR8h3JJz_s8nYvSbfJM4lLvo,4113
+proton/run_status.py,sha256=m5lD3a0nVOvmMvoxxb6Ch04Pno370J2xGuvg0fx6XNk,223
+protoncloud_sdk-5.0.0.dist-info/METADATA,sha256=mfVlD5Nckz8EXEWqCX3iwXo3Onr81SSVi3q7wfn4tDU,3721
+protoncloud_sdk-5.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+protoncloud_sdk-5.0.0.dist-info/licenses/LICENSE,sha256=FQ6Qm5N4ElW76McTRb-CEyjUAHvWkKOYllXmix3SgDw,530
+protoncloud_sdk-5.0.0.dist-info/RECORD,,

protoncloud_sdk-5.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

protoncloud_sdk-5.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) Atomic Solutions. Todos os direitos reservados.
+
+Este software é proprietário. O uso é permitido exclusivamente em conjunto com
+a plataforma Proton, por licenciados da Atomic Solutions e nos termos do
+contrato firmado com a empresa.
+
+Não é concedida permissão para redistribuir, sublicenciar, vender ou criar
+trabalhos derivados a partir deste software sem autorização prévia por escrito
+da Atomic Solutions.
+
+O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER NATUREZA, EXPRESSA
+OU IMPLÍCITA.