Types — Calimero Client Py

Exports

All types are re-exported from the top-level calimero package:

from calimero import (
  ConnectionInfo,
  Client,
  JwtToken,
  ClientError,
  AuthMode,
  create_connection,
  create_client,
  get_token_cache_path,
  get_token_cache_dir,
)

AuthMode

src/auth.rs · calimero_client_py.AuthMode

Represents whether a node requires authentication. Returned by ConnectionInfo.detect_auth_mode() and can be constructed directly.

Values

"none"

No authentication required. The node accepts unauthenticated requests.

"required"

Authentication is required. A valid JWT token must be obtained before making API calls.

Usage

# Detect from node
mode = conn.detect_auth_mode()
print(mode.value) # "none" or "required"
str(mode) # "none" or "required"

# Construct directly
mode = calimero.AuthMode("required")

Properties

.value

str — Either "none" or "required".

JwtToken

src/token.rs · calimero_client_py.JwtToken

Wraps a JWT access/refresh token pair used to authenticate requests to a Calimero node. Tokens are cached automatically when a node_name is provided to create_connection().

Note

Automatic management

In normal usage, you do not need to interact with JwtToken directly. The Merobox authenticator handles token acquisition and refresh transparently. This type is exposed for introspection or advanced use cases.

ClientError

src/error.rs · calimero_client_py.ClientError

Raised when the Rust client layer encounters an error — network failures, node-returned error responses, or serialization issues. Use it to distinguish node errors from bad argument errors (ValueError).

Error handling pattern

try:
  result = client.list_contexts()
except calimero.ClientError as e:
  # Node/network-level failure
  print(f"Client error: {e}")
except ValueError as e:
  # Bad argument (invalid ID format, etc.)
  print(f"Bad input: {e}")
except RuntimeError as e:
  # Unexpected internal error
  print(f"Runtime error: {e}")

When each exception is raised

ClientError

Node returned an error response, connection refused, authentication failure, or serialization of the response failed.

ValueError

A passed argument could not be parsed — e.g. an invalid context ID, application ID, blob ID, or malformed URL.

RuntimeError

The Tokio runtime failed to start, or another unexpected internal error occurred in the Rust layer.