Migrer vers la v5

La v5 est une réécriture. Le SDK est désormais synchrone par défaut (avec une façade await), n’a aucune dépendance, regroupe les méthodes par ressource, renvoie des dicts simples (TypedDict) et lève un seul type d’exception. Il couvre les 67 opérations de l’API Square Cloud.

En un coup d’œil

v4	v5
`await client.x(...)`, asynchrone uniquement	`client.group.x(...)`, ou `await async_client.group.x(...)`
Dataclasses figées (`status.ram`)	`TypedDict`, un dict simple (`status['ram']`) ; les champs inconnus sont conservés au lieu de lever une `TypeError`
Objets `Application` (`app.start()`, `app.cache`)	Des données brutes plus des identifiants : `client.apps.start(app_id)`. Il n’y a pas de cache
~25 classes d’exception (`NotFoundError`, `TooManyRequests`, `FewMemory`, …)	`SquareCloudAPIError` avec `.status`, `.code`, `.message`, `.method`, `.path` (`'/v2/...'`), `.cause`
`squarecloud.File(path)`	Passez directement un chemin, des `bytes` ou un objet fichier binaire
Arguments optionnels par position	Les modificateurs optionnels sont uniquement nommés (`status(id, raw=True)`, `commit(id, file, path=...)`, `databases.create(name, type=, version=, memory=)`)
Listeners de requêtes (`@client.on_request`), listeners de capture, `avoid_listener`, `update_cache`	Supprimés. Utilisez le logger `squarecloud` (DEBUG) ou un `transport=` personnalisé
Dépendances `aiohttp` et `typing-extensions`	Aucune
Python `>=3.13,<3.15`	Python `>=3.11`, sans borne supérieure

Construction et options

v4	v5
`squarecloud.Client(api_key, log_level=...)`	`SquareCloud(api_key, *, base_url=BASE_URL, timeout=30.0, max_retries=2, transport=None, user_agent=...)`, ou `AsyncSquareCloud(...)` avec les mêmes arguments
`log_level=` et un handler coloré attaché à l’import	`logging.getLogger('squarecloud')` avec un `NullHandler` ; configurez-le vous-même
Valeurs par défaut d’`aiohttp` (5 min par requête ; 90 s entre deux lectures temps réel)	`timeout` en secondes par opération de socket, avec un plancher de 120 s pour les appels maintenus ouverts et l’IA ; `timeout <= 0` désactive tous les timeouts
Aucune nouvelle tentative	`max_retries` (2) pour les seuls échecs sans risque ; un 429 n’est jamais réessayé
`User-Agent` codé en dur	`user_agent=` remplace l’en-tête (par défaut `squarecloud-sdk-py/<version>`)
Une nouvelle session par requête	`close()` ou `with` / `async with` ferme les connexions keep-alive du pool

Méthode par méthode

ancien (v4 `Client`)	nouveau (v5 `SquareCloud`)	remarques
`user()`	`account.me()['user']`	`me()` renvoie aussi `applications` et `databases`
`all_apps()`	`account.me()['applications']`
`app(app_id)`	`apps.get(app_id)`	Désormais `GET /apps/{id}` : fonctionne avec les identifiants de workspace `'<appId>-<workspaceId>'`
`user_snapshots(scope)`	`account.snapshots(*, scope=None)`	`scope` est uniquement nommé. Les éléments portent le `version_id` et l’`url` signée de l’API
`service_status()`	`service.status()`
`upload_app(File(path))`	`apps.create(path)`	Diffusé en flux depuis le disque ; renvoie `AppCreated` (`domain` est l’hôte complet d’un site ; il n’y a pas de `subdomain`)
`delete_app(id)`	`apps.delete(id)`	Renvoie `None`
`all_apps_status()`	`apps.status_all(*, workspace_id=None)`	Les applications arrêtées ne sont plus omises
`app_status(id)`	`apps.status(id, *, raw=False)`	`raw=True` (uniquement nommé) renvoie des nombres
`start_app` / `stop_app` / `restart_app`	`apps.start` / `apps.stop` / `apps.restart`	Renvoient `None`
`get_logs(id)`	`apps.logs(id)`	Renvoie la `str`
`app_metrics(id)`	`apps.metrics(id)`
`realtime(id)` (générateur asynchrone de chaque ligne `data:`, décodée en JSON si possible)	`apps.realtime(id)`	Itérateur de `{'event', 'data', 'id'}` avec le texte brut de `data`, plus `stream`/`line` sur les logs et le `status` fusionné sur les événements de statut. Se reconnecte tout seul (voir Changements de comportement) ; le flux n’a pas de timeout de lecture (la v4 abandonnait après 90 s sans données), arrêtez-le donc avec `close()`
`all_domains()`	`apps.domains()`
`load_balancers()`	`apps.load_balancers()`
`commit(id, File(path))`	`apps.commit(id, file, *, path=None, filename=None)`	`path` uniquement nommé = répertoire de destination ; `filename` nomme un fichier non zip (les `bytes` prennent par défaut `commit.zip`)
`github_integration(id, access_token)`	`apps.deploys.set_webhook(id, access_token)`
`last_deploys(id)`	`apps.deploys.list(id)`	Les événements incluent `source`, `branch`, `files` ; un deploy échoué se termine par `state='error'` plus `code` et `message`
`current_app_integration(id)`	`apps.deploys.current(id)`	Renvoie `{'app'?, 'webhook'?}` au lieu de la chaîne du webhook
`get_app_envs` / `set_app_envs` / `overwrite_app_envs` / `delete_app_envs`	`apps.envs.get` / `set` / `replace` / `delete`
`clear_app_envs(id)`	`apps.envs.replace(id, {})`
`app_files_list(id, path)`	`apps.files.list(id, path=None)`	Les entrées sont les `FileEntry` de l’API (sans `path`/`app_id` calculés). Un répertoire inexistant lève 404 `FILE_NOT_FOUND` au lieu de renvoyer `[]` ; un répertoire bloqué donne 403 `BLOCKED_PATH`
`read_app_file(id, path)` → `BytesIO`	`apps.files.read(id, path)` → `bytes`	Récupéré encodé en base64 (`?encoding=base64`) puis décodé ; au-delà de 10 Mo, donne 413 `FILE_TOO_LARGE`
`create_app_file(id, File(...), path)`	`apps.files.write(id, path, content)`	Une `str` est envoyée en texte, des `bytes` encodés en base64 (compatible binaire) ; chemin envoyé tel quel (sans `/` supplémentaire) ; un contenu vide (`''` ou `b''`) crée un fichier vide
`move_app_file(id, origin, dest)`	`apps.files.move(id, path, to)`
`delete_app_file(id, path)`	`apps.files.delete(id, path)`
`snapshot(id)` → `Snapshot`	`apps.snapshots.create(id)`	`{'pending': True}` sur un 202 au lieu de lever une erreur ; interrogez ensuite `list`, ne recréez jamais
`all_app_snapshots(id)`	`apps.snapshots.list(id)`	Les éléments portent le `version_id` et l’`url` de téléchargement signée de l’API, transmis tels quels
`restore_snapshot('app', id, snapshot_id, version_id)`	`apps.snapshots.restore(id, name, version_id)`	`name` et `version_id` d’un élément de `list`
`restore_snapshot('database', id, ...)`	`databases.snapshots.restore(id, name, version_id)`	`name` et `version_id` d’un élément de `list`
`Snapshot.download(path)`	`client.download_snapshot(url, dest)`	Diffuse le zip lui-même (la v4 l’enveloppait dans un autre zip)
`domain_analytics(id, start=, end=, ...)`	`apps.network.analytics(id, start, end, *, country=, ...)`	`start`/`end` sont exigés par l’API ; les filtres sont uniquement nommés
`network_errors(id, start, end, include_4xx)` / `network_logs` / `network_performance`	`apps.network.errors(id, start, end, *, include_4xx=False)` / `logs` / `performance`	`analytics`, `errors` et `performance` renvoient `None` pour une fenêtre sans données
`dns_records(id)`	`apps.network.dns(id)`
`set_custom_domain(id, custom_domain)`	`apps.network.set_domain(id, domain)`	La v4 n’envoyait jamais le corps
`purge_cache(id)`	`apps.network.purge_cache(id)`
`link_github_app(id, repository_name, repository_branch)`	`apps.deploys.link_github_app(id, repository, branch)`	Fonctionne désormais avec une clé API (scope `apps:deploy`) ; renvoie le `LinkedRepository` (`{id, full_name, branch}`) au lieu du dict brut ; 403 `GITHUB_NOT_CONNECTED` sans installation de la GitHub App
`unlink_github_app(id)`	`apps.deploys.unlink_github_app(id)`	Renvoie `None` ; 400 `GIT_NOT_CONFIGURED` quand rien n’est lié
`create_database(name, memory, type, version=None)`	`databases.create(name, type=, version=, memory=)`	Uniquement nommés ; `version` est obligatoire (une version majeure comme `'8'` fonctionne)
`get_database_info(id)`	`databases.get(id)`
`edit_database(id, name, memory)`	`databases.update(id, name=, ram=)`	La v4 envoyait `memory`, que l’API ignorait
`delete_database` / `start_database` / `stop_database`	`databases.delete` / `start` / `stop`
`get_database_status(id)`	`databases.status(id, *, raw=False)`
`all_databases_status()`	`databases.status_all()`
`database_metrics(id)`	`databases.metrics(id)`
`get_database_certificate(id)` → `Certificate`	`databases.certificate(id)` → `str` en base64	`base64.b64decode(...)` donne le PEM
`reset_database_password(id)`	`databases.reset_credentials(id, 'password')`	Renvoie le nouveau mot de passe
`reset_database_certificate(id)`	`databases.reset_credentials(id, 'certificate')`	Renvoie `''`
`all_database_snapshots(id)` / `database_snapshot(id)`	`databases.snapshots.list(id)` / `create(id)`	Les éléments portent `version_id` et `url`, comme pour les applications
`create_workspace(name)`	`workspaces.create(name)`	Renvoie `{id, name}` en une seule requête
`all_workspaces()` / `get_workspace(id)`	`workspaces.list()` / `workspaces.get(id)`	La v4 réécrivait l’`id` de chaque application sous la forme composite `'<appId>-<workspaceId>'` ; la v5 renvoie l’identifiant brut de l’API, construisez-le donc vous-même : `f"{app['id']}-{workspace['id']}"`
`delete_workspace` / `leave_workspace`	`workspaces.delete` / `workspaces.leave`
`add_member_to_workspace(ws, invite_code, permissions)`	`workspaces.members.add(ws, code, group)`
`modify_member_permissions(ws, user_id, permissions)`	`workspaces.members.update(ws, member_id, group)`
`remove_member_from_workspace(ws, user_id)`	`workspaces.members.remove(ws, member_id)`
`get_invite_code()`	`workspaces.members.invite_code()`
`add_app_to_workspace` / `remove_app_from_workspace`	`workspaces.apps.add` / `workspaces.apps.remove`
—	`ai.chat(request)`	Nouveau ; `request` est le corps de style OpenAI (`{'messages': [...], 'model': ...}`)
`client.api_key`	Supprimé	Gardez votre propre référence à la clé
`on_request(endpoint)`, `Application.capture(endpoint)`	Supprimés	Voir la ligne des listeners dans En un coup d’œil
`squarecloud.utils.ConfigFile`	Supprimé	Écrivez vous-même le fichier `squarecloud.app` (lignes `KEY=value`)

Les méthodes d’Application correspondent aux mêmes appels avec l’identifiant : app.logs() → client.apps.logs(app.id), app.files_list(path) → client.apps.files.list(app.id, path), et ainsi de suite.

Types

Les réponses sont des TypedDict de squarecloud.types, nommés comme dans les SDK JS et Go : Account, User, Plan, AppSummary, DatabaseSummary, App, AppCreated, StatusListItem, RuntimeStats, MetricPoint, AppDomain, LoadBalancers, DeployEvent, DeployCurrent, DeployRepository, LinkedRepository, EnvVars, FileEntry, Snapshot, SnapshotCreated, SnapshotScope, AnalyticsFilters, NetworkAnalytics, NetworkErrors, NetworkLog, NetworkPerformance, DNSRecord, Database, DatabaseCreated, DatabaseType, Workspace, WorkspaceCreated, WorkspaceGroup, ServiceStatus, ServiceEntry, ChatRequest, ChatMessage, ChatCompletion, RealtimeEvent, RealtimeStatus. Ils remplacent les dataclasses data/* de la v4 (UserData, StatusData, AppData, …). squarecloud.Response est désormais le protocole de réponse du transport (voir Transport personnalisé) ; le Response de la v4 que renvoyaient les mutations a disparu, et celles-ci renvoient None.

Erreurs

v4	v5
`AuthenticationFailure`	`e.status == 401` (`ACCESS_DENIED`, y compris pour une clé expirée)
`NotFoundError`, `ApplicationNotFound`	`e.status == 404` (`APP_NOT_FOUND`, `WORKSPACE_NOT_FOUND`, …)
`BadRequestError` et la famille `InvalidConfig`	`e.status == 400`, vérifiez `e.code`
`TooManyRequests`	`e.status == 429` (`RATE_LIMITED`, `KEEP_CALM`)
`FewMemory` (jamais levée : l’API envoie `INSUFFICIENT_MEMORY`)	`e.code == 'INSUFFICIENT_MEMORY'`
`InvalidDomain` (`REGEX_VALIDATION`, qui n’est plus envoyé)	`e.code == 'INVALID_DOMAIN'`
`RequestError` pour 403/503	`e.code` parmi `MISSING_SCOPE`, `RESOURCE_NOT_ALLOWED`, `BLOCKED_PATH`, `UPLOAD_BUSY`, …
Exceptions `aiohttp` qui s’échappent	`e.status == 0`, `e.code` parmi `NETWORK_ERROR`, `TIMEOUT` (exception d’origine dans `e.cause`)
—	`e.status == 0` avec `FILE_TOO_LARGE` ou `INVALID_ID` : vérifications locales, rien n’a été envoyé
HTML de proxy ou corps non JSON qui s’échappe	`UNKNOWN_ERROR` avec le vrai statut et le message `HTTP <status>` (`Invalid JSON in HTTP <status> response` sur un 2xx)

str(e) vaut '<METHOD> <path>: HTTP <status> <CODE>: <message>', sans HTTP <status> lorsque le statut est 0 et sans : <message> lorsqu’il est vide. e.message vaut '' lorsque le serveur n’a envoyé qu’un code.

Changements de comportement

Les modificateurs optionnels sont uniquement nommés : account.snapshots(scope=), apps.status_all(workspace_id=), apps.status(id, raw=), databases.status(id, raw=), apps.commit(id, file, path=, filename=), apps.network.errors(..., include_4xx=), les filtres de apps.network.analytics(...), databases.update(id, name=, ram=) et databases.create(name, type=, version=, memory=). Le path optionnel de apps.files.list reste positionnel.
Un corps 2xx {"status": "error"} lève une erreur. Les refus de démarrage/arrêt des applications et des bases de données donnent 409 avec seulement un code (CONTAINER_ALREADY_STARTED, ACTION_FAILED, …). Un 202 SNAPSHOT_PROCESSING renvoie {'pending': True} au lieu de lever une erreur : interrogez list, n’appelez jamais create à nouveau.
Les valeurs de requête optionnelles non définies (et '') sont omises au lieu d’être envoyées.
Les résultats de type chaîne ne sont jamais None : reset_credentials(id, 'certificate') et un webhook supprimé renvoient ''.
apps.files.write envoie une str en texte et des bytes encodés en base64 ; un contenu vide crée un fichier vide ; un contenu de plus de 1 MiB est envoyé sans timeout. apps.files.read demande toujours du base64 et renvoie les bytes décodés.
apps.files.list sur un répertoire inexistant lève 404 FILE_NOT_FOUND.
503 DATABASE_UNAVAILABLE n’est réessayé que sur GET, car il peut survenir après l’application d’une mutation ; réessayer une mutation idempotente revient à l’appelant.
Le flux temps réel produit des événements {'event', 'data', 'id', ...}, se rouvre au plus 3 fois d’affilée à raison d’une ouverture toutes les 5,5 s, et lève une erreur lorsqu’une ouverture échoue.

Asynchrone

La v4 était uniquement asynchrone. Dans la v5, SquareCloud est synchrone et AsyncSquareCloud est la façade await : les mêmes groupes et méthodes, chaque appel étant exécuté dans asyncio.to_thread, de sorte que la boucle d’événements n’est jamais bloquée. Le flux temps réel devient async for (un thread de lecture alimente la boucle) ; fermez-le avec async with ou close(). v4 :

client = squarecloud.Client(key)
status = await client.app_status(app_id)
print(status.ram)
async for data in client.realtime(app_id):
    print(data)

v5 :

async with squarecloud.AsyncSquareCloud(key) as client:
    status = await client.apps.status(app_id)
    print(status['ram'])
    async with client.apps.realtime(app_id) as stream:
        async for event in stream:
            print(event['data'])

Services

Runtimes

Plateforme

Dépannage

CLI

SDKs

Changelog

En un coup d’œil

Construction et options

Méthode par méthode

Types

Erreurs

Changements de comportement

Asynchrone

​En un coup d’œil

​Construction et options

​Méthode par méthode

​Types

​Erreurs

​Changements de comportement

​Asynchrone

En un coup d’œil

Construction et options

Méthode par méthode

Types

Erreurs

Changements de comportement

Asynchrone