Client — Calimero Client Py

Constructor

Create a Client from an existing ConnectionInfo. All methods are synchronous — the Tokio runtime is managed internally. Responses are returned as Python dict / list (JSON-deserialized).

import calimero

conn = calimero.create_connection(
api_url="https://node.example.com",
node_name="prod-node"
)
client = calimero.create_client(conn)

get_api_url()

Returns the node URL this client is connected to.

url: str = client.get_api_url()

Contexts

list_contexts()

Returns all contexts on the node.

contexts = client.list_contexts()

get_context(context_id)

Returns details of a single context by its ID string.

ctx = client.get_context("abc123…")

create_context(application_id, group_id, params?, service_name?)

Creates a new context for an installed application. params is a JSON string of initialization parameters. service_name is an optional service qualifier.

ctx = client.create_context(
"app-id", "group-id",
params='{"key":"val"}'
)

delete_context(context_id)

Permanently deletes a context by ID.

sync_context(context_id)

Triggers a sync for a specific context.

sync_all_contexts()

Triggers a sync for all contexts on the node.

update_context_application(context_id, application_id, executor_public_key)

Upgrades a context to a different (or newer) application version.

get_context_storage(context_id)

Returns storage usage stats for a context.

Identities & Keys

get_context_identities(context_id)

Lists all identity public keys associated with a context.

get_context_client_keys(context_id)

Returns the client keys registered for a context.

generate_context_identity()

Generates a new keypair for use in contexts. Returns the public key and associated metadata.

identity = client.generate_context_identity()

get_peers_count()

Returns the number of peers currently connected to the node.

count = client.get_peers_count()

Applications

list_applications()

Returns all applications installed on the node.

get_application(app_id)

Returns details of an installed application by its ID.

install_application(url, hash?, metadata?)

Installs an application from a remote URL. The optional hash (hex string, 32 bytes) verifies integrity. metadata is raw bytes (defaults to b"{}").

result = client.install_application(
"https://example.com/app.wasm",
hash="ab12cd…"
)

install_dev_application(path, metadata?)

Installs a local WASM file for development. Accepts a UTF-8 filesystem path.

result = client.install_dev_application("/path/to/app.wasm")

uninstall_application(app_id)

Removes an installed application by its ID.

Blobs

list_blobs()

Returns all blobs stored on the node.

get_blob_info(blob_id)

Returns metadata about a blob by its ID string.

upload_blob(data, context_id?)

Uploads raw bytes as a blob. Optionally scoped to a context_id. Returns blob metadata including the new blob ID.

info = client.upload_blob(b"hello world")

download_blob(blob_id, context_id?)

Downloads a blob by ID. Returns raw bytes.

data: bytes = client.download_blob("blob-id")

delete_blob(blob_id)

Permanently deletes a blob by its ID.

Error Handling

Methods raise calimero.ClientError for node/network failures and ValueError for malformed arguments (bad IDs, invalid URLs).

try:
  ctx = client.get_context("bad-id")
except calimero.ClientError as e:
  print(f"Node error: {e}")
except ValueError as e:
  print(f"Bad argument: {e}")

See Types for a full breakdown of when each exception is raised.