Dependências e ficheiros

Um script raramente é só o main.py. Esta página cobre tudo o que vive à volta dele: os ficheiros do script (módulos Python, configuração, dados gerados), os packages pip instalados no ambiente dele, e os scripts usados como dependência — código de outro script, desta app ou de outra, importado pelo teu.

Tudo isto se gere na árvore lateral: expande o nó do script (a seta à esquerda do nome) e aparecem três entradas — Ficheiros, Dependências e Agendamentos. As duas primeiras são o assunto desta página.

#A pasta do script

Cada script tem uma pasta privada no servidor. É lá que vivem o main.py, os módulos que criares, os ficheiros que carregares e tudo o que o script escrever em disco durante as execuções. Dois pontos importantes:

• A pasta é a pasta de trabalho das execuções: um caminho relativo no código (open("dados/clientes.csv")) lê e escreve lá dentro.
• A pasta é privada do script — outro script não lhe toca, nem por engano.

O nó Ficheiros na árvore mostra a pasta tal como ela está, com a contagem de ficheiros à frente. Clicar num ficheiro abre-o no editor do script.

#Criar ficheiros e pastas

Passa o rato pela linha Ficheiros para ver os três botões dela:

Botão	O que faz
Novo ficheiro	Cria um ficheiro de qualquer extensão — código, config, dados.
Nova pasta	Cria uma pasta lógica dentro da pasta do script.
Carregar ficheiros	Envia ficheiros do teu computador para a pasta do script.

Para criar um ficheiro:

1. Clica em Novo ficheiro.
2. Preenche Caminho do ficheiro — ex.: utils.py ou dados/clientes.csv. Subpastas escrevem-se com / e são criadas se não existirem.
3. Clica em Criar. Se for um ficheiro de texto, abre logo no editor.

Gestos directos na árvore:

• Renomear: duplo clique no nome, escreve, Enter.
• Mover: arrasta o ficheiro (ou a pasta) para outra pasta da árvore.
• Remover: o × que aparece ao passar o rato na linha. A remoção é imediata e definitiva — e os import que usavam o ficheiro passam a falhar.
• Carregar: além do botão, podes arrastar ficheiros do teu computador directamente para a árvore — largá-los numa pasta envia-os para lá.

#Dividir o script em módulos

Podes partir o código em quantos ficheiros .py quiseres — todos na pasta do script — e importá-los directamente, sem configuração:

# config.py
CONFIG = {"limite": 100, "moeda": "EUR"}

# main.py
from api_manager import db, log
from config import CONFIG


def main(input):
    linhas = db("Dados CRM").query(
        "select * from oportunidades limit ?", [CONFIG["limite"]]
    )
    log(len(linhas), "oportunidades lidas")
    return {"total": len(linhas)}

O editor conhece os teus módulos: o autocompletar sugere from config import … como sugere o SDK.

#Ficheiros gerados pelas execuções

O script pode escrever ficheiros à vontade — um Excel gerado para enviar por email, um CSV de trabalho, um cache. Ficam na pasta do script e aparecem no nó Ficheiros, onde os podes abrir no editor ou remover.

Dois limites do editor (não do script):

• Ficheiros binários (um .xlsx, uma imagem) não abrem no editor — a árvore avisa. O script continua a lê-los e escrevê-los normalmente.
• Ficheiros de texto acima de 10 MB também não abrem no editor, pela mesma razão — o script continua a poder usá-los.

#Instalar packages pip

A biblioteca padrão do Python está sempre disponível. Para packages externos (requests, pandas, openpyxl, …), cada script tem o seu próprio ambiente Python, isolado dos outros — instalar aqui não muda nada nos outros scripts.

1. Na árvore, expande o script e clica na chave inglesa da linha Dependências (Gerir dependências (packages e scripts)).
2. No modal Dependências do script (pip + scripts), secção Adicionar package do PyPI, escreve o nome exacto do package — ex.: openpyxl — e clica em Verificar. A plataforma confirma no PyPI que ele existe e mostra o nome, a versão mais recente e a descrição.
3. Clica em Instalar. O package fica na tabela Packages instalados, com a versão.
4. No código, importa normalmente: import openpyxl.

A linha Ambiente Python: no topo do modal diz o estado do ambiente do script:

Estado	Significa
por criar (cria-se na primeira instalação ou execução)	Ainda nenhum package foi instalado nem o script correu.
pronto	O ambiente existe e está utilizável — a versão do Python aparece ao lado.
danificado	Algo partiu o ambiente (ex.: uma actualização no servidor). Usa Reconstruir venv.

Mais três gestos no mesmo modal:

• Reinstalar — aparece no lugar de Instalar quando o package já lá está; força uma reinstalação.
• Desinstalar — na linha do package instalado. Os import desse package no script passam a falhar até ele ser reinstalado.
• Reconstruir venv — apaga e recria o ambiente inteiro, reinstalando todos os packages da lista. Útil depois de uma actualização do Python no servidor.

#Scripts como dependência

Além de packages, um script pode reutilizar outro script — desta app ou de outra a que tenhas acesso. Os ficheiros do script referenciado ficam disponíveis numa pasta com o alias que escolheres, sincronizada antes de cada execução: corriges o script original, e quem depende dele passa a usar a versão corrigida.

1. Abre o gestor de dependências (chave inglesa da linha Dependências).
2. Na secção Scripts como dependência: escolhe a App, escolhe o Script, e dá-lhe um Alias (import) — ex.: consolidado. O alias tem de ser um identificador Python válido.
3. Clica em Adicionar.
4. No código, importa pelos módulos do alias:

from consolidado.main import main as consolidar


def main(input):
    resultado = consolidar({"args": {}, "prev": None, "context": {}})
    return {"consolidado": resultado}

Regras que a plataforma impõe ao adicionar:

• Só aparecem scripts do mesmo runtime e de apps a que tens acesso.
• Um script não pode depender de si próprio.
• O alias não pode repetir-se nem coincidir com um ficheiro ou pasta que já exista na pasta do script.

Para remover, usa o × da linha da dependência (na árvore ou no gestor). A pasta do alias sai do disco e os import que a usavam falham na próxima execução.

#Perguntas frequentes

Instalei um package e o import continua a falhar. Confirma o nome exacto do módulo — o package Pillow importa-se como PIL, por exemplo. A tabela Packages instalados mostra o nome do package; o nome do módulo vem da documentação dele.

Porque não consigo apagar o requirements.txt? É um dos três ficheiros protegidos — é a lista de packages do script, mantida pelo painel de dependências. Para tirar um package, usa Desinstalar no gestor de dependências, não o ficheiro.

Um colega mudou o script de que eu dependo. Quando é que o meu apanha a mudança? Na execução seguinte: a pasta do alias é sincronizada antes de cada execução do teu script.