Esta página documenta o
squarecloud-api 5.0, uma reescrita do SDK. Vindo da v4? Leia o guia de migração v4 → v5.Requisitos
- Python 3.11 ou superior.
- Uma chave de API (veja Chave de API e escopos).
http.client, json, ssl) e é totalmente tipado (py.typed): as respostas são TypedDicts que seu editor e seu verificador de tipos entendem.
Instalação
- pip
- uv
- poetry
squarecloud-api e importado como squarecloud. A versão instalada é squarecloud.__version__.
Chave de API e escopos
Crie uma chave em squarecloud.app/account/security. O SDK a envia como está no headerAuthorization (sem o prefixo Bearer).
Uma chave pode ser limitada a escopos (apps:read, apps:deploy, apps:control, ai:chat, …) e a aplicações ou bancos de dados específicos:
- Uma chamada fora desses limites lança um
SquareCloudAPIErrorcom 403MISSING_SCOPEouRESOURCE_NOT_ALLOWED. - Métodos de listagem (
account.me(),apps.status_all(), …) retornam apenas os recursos que a chave pode ver. - Uma chave desconhecida, revogada ou expirada resulta em 401
ACCESS_DENIED.
SQUARECLOUD_API_KEY. Defina-a no terminal em que você vai executá-los:
- macOS / Linux
- Windows (PowerShell)
Criando o cliente
O SDK tem dois clientes com os mesmos grupos e métodos:SquareCloudé síncrono e thread-safe: compartilhe uma única instância entre threads. Cada thread reutiliza sua própria conexão keep-alive.AsyncSquareCloudé a mesma API comawait. Cada chamada executa o cliente síncrono emasyncio.to_thread, então o event loop nunca é bloqueado.
- Síncrono
- Assíncrono
with / async with fecha as conexões do pool. Sem um bloco, chame client.close() quando terminar. close() é um método comum (síncrono) nos dois clientes.
Uma chave vazia ou composta apenas de espaços lança um ValueError no construtor, antes de qualquer requisição.
O cliente assíncrono
AsyncSquareCloud difere de SquareCloud em apenas três pontos:
- Todo método retorna uma coroutine:
await client.apps.status(app_id). close()é síncrono: chame-o semawait.apps.realtime(app_id)não é aguardado: ele retorna umAsyncRealtimeque você consome comasync for(veja Tempo real).
asyncio.gather:
Cancelar uma task em espera não interrompe a requisição que já está rodando na sua thread de trabalho: a chamada ainda termina (ou expira) em segundo plano.
Opções
AsyncSquareCloud recebe as mesmas.
O cliente guarda a chave apenas nos seus headers privados de requisição: não existe um atributo
client.api_key, e o logger do SDK nunca a escreve.Módulos
O pacote exporta
SquareCloud, AsyncSquareCloud, SquareCloudAPIError, BASE_URL, HTTPTransport, os protocolos Transport e Response, Realtime, AsyncRealtime e __version__. Os tipos de resposta (App, RuntimeStats, Snapshot, …) ficam em squarecloud.types:
Convenções
Ids primeiro, dados simples de volta
Todo método recebe o id do recurso como primeiro argumento e retorna dados simples: cada resposta é umTypedDict, que em tempo de execução é um dict comum (sem classes, sem cache), então os campos que a API adicionar no futuro são mantidos. Os nomes dos campos são os da própria API (created_at, version_id, lastModified, joinedAt, netIO, …), então a referência da API se aplica diretamente.
- Mutações retornam
None, a menos que a API retorne dados (envs.*,deploys.set_webhook,deploys.link_github_app,databases.reset_credentialse os métodoscreate). - Um resultado string nunca é
None: ele é''quando a API não envia nada. - Listas vêm completas em uma única chamada: não há paginação.
- Modificadores opcionais são keyword-only (
status(app_id, raw=True),commit(app_id, file, path="/src")). A única exceção é opathopcional defiles.list, que também pode ser passado por posição.
Aplicações de workspace
Todoapp_id também aceita a forma composta <appId>-<workspaceId> para atuar sobre uma aplicação compartilhada com você por meio de um workspace. workspaces.get() e workspaces.list() retornam ids brutos; você mesmo monta o id composto:
Ids são codificados
Ids no caminho da URL são codificados com percent-encoding. Um id vazio,. ou .. chegaria a uma rota diferente, então ele falha localmente com INVALID_ID (status 0) antes que qualquer coisa seja enviada. As rotas de workspace enviam seus ids no corpo: nelas, o INVALID_ID (400) vem do servidor.
Datas
Os argumentosstart e end (veja Rede) aceitam uma string ISO 8601 (enviada como está) ou um datetime (enviado em UTC). Um datetime naive é tratado como horário local e convertido para UTC, então prefira os aware (datetime.now(UTC)). As datas nas respostas permanecem como a API as envia (strings ISO, ou milissegundos Unix onde a API os usa).
Timeouts
timeout limita cada operação de socket: a conexão e cada leitura ou escrita. Uma resposta que continua enviando dados pode levar mais do que timeout no total.
Um
timeout de 0 ou menos desativa todos os timeouts, incluindo os mínimos de 120 s.
As chamadas não podem ser canceladas depois de enviadas: o único stream que você pode interromper no meio é o apps.realtime(), com close() a partir de qualquer thread. Para um upload longo, mantenha o timeout padrão para que uma conexão morta seja detectada na conexão, e execute-o em uma thread ou com o AsyncSquareCloud se o resto do seu programa precisar continuar rodando.
Conta
client.account.me() retorna o usuário autenticado, além das aplicações e bancos de dados que a chave pode ver.
client.account.snapshots(scope=...) lista todos os snapshots da conta: veja Snapshots.
Status da plataforma
client.service.status() retorna o status público da plataforma. A rota não exige uma chave válida, mas o cliente ainda requer uma chave não vazia.
unknown significa que a própria verificação não pôde ser executada: não é evidência de uma indisponibilidade.
Avançado
Transporte personalizado
transport= substitui a camada HTTP. Use-o para proxies, tracing ou testes. Um transporte é qualquer callable com esta assinatura:
O objeto retornado precisa de
status, read(), readline() e close(): um http.client.HTTPResponse serve. As novas tentativas, o mapeamento de erros e o desempacotamento de {status, response} ficam no cliente, então um transporte apenas move bytes.
HTTPTransport(timeout=30.0) é o transporte padrão: uma conexão keep-alive por thread e host, respostas comprimidas com gzip (exceto em streams) e timeout como limite de conexão das chamadas sem timeout próprio. Você pode encapsulá-lo:
client.close() fecha as conexões do transporte padrão. Um transporte personalizado que tenha um método close() também é fechado.
Registro de logs
O SDK registra cada requisição emDEBUG no logger squarecloud: método, caminho e status, nunca corpos ou chaves. Ele apenas anexa um NullHandler, então nada é impresso até você configurar o logging:
Próximos passos
Gerenciando aplicações
Status, ciclo de vida, logs e métricas.
Erros
Classe de erro, novas tentativas e rate limits.
Introdução à API
URL base, autenticação e uma primeira requisição.
Início rápido da CLI
Faça deploy e gerencie aplicações pelo terminal.

