Skip to main content
Version: Next

Python Client SDK

The Calimero Python Client SDK provides a comprehensive, high-performance interface for interacting with Calimero Network APIs. Built with Rust and PyO3, it offers native performance with the ease of Python development.

Overview​

The Python client library is designed for developers who want to build Calimero applications using Python, whether for web development, data analysis, automation, or integration with existing Python ecosystems.

Key Features​

  • 🚀 High Performance: Built with Rust and PyO3 for optimal performance.
  • 🔒 Type Safety: Strongly typed Python bindings with full IDE support.
  • ⚡ Synchronous Interface: Clean synchronous API with Rust-powered backend.
  • 🌐 Multi-Protocol: Support for NEAR, Ethereum, ICP, and Starknet networks.
  • 📦 Easy Installation: Simple pipx install with no complex dependencies.
  • 🔧 Comprehensive API: Full access to all Calimero Network functionality.

Supported Protocols​

  • ✅ NEAR Protocol - Account-based architecture with optimized storage.
  • ✅ Ethereum - Full EVM compatibility with gas optimization.
  • ✅ Internet Computer Protocol (ICP) - Canister-based execution model.
  • ✅ Starknet - Cairo-based smart contracts with account abstraction.

Quick Start​

Installation​

Install the Python client from PyPI:

pipx install calimero-client-py
pipx ensurepath

Basic Usage​

import calimero

def main():
    # Create a connection
    connection = calimero.create_connection(
        api_url="http://localhost:2428",
        node_name="example-node"
    )

    # Create a client
    client = calimero.create_client(connection)

    # List available contexts
    contexts = client.list_contexts()
    print(f"Found {len(contexts)} contexts")

    # List applications
    apps = client.list_applications()
    print(f"Found {len(apps)} applications")

if __name__ == "__main__":
    main()

CLI Usage​

The Python client includes a command-line interface:

# Install the CLI
pipx install calimero-client-py
pipx ensurepath

# Use the CLI (requires a running Calimero node)
calimero-client-py --help
calimero-client-py --version
calimero-client-py --base-url http://localhost:2428 list-contexts

Note: The CLI requires a running Calimero node to function properly. If no node is running, you'll get connection errors.

Architecture​

Synchronous Interface​

The client provides a clean synchronous interface with high performance:

import calimero

def example():
    connection = calimero.create_connection("http://localhost:2428")
    client = calimero.create_client(connection)

    # All operations are synchronous
    contexts = client.list_contexts()
    apps = client.list_applications()

    return contexts, apps

Core Components​

Connection Management​

import calimero

# Basic connection
connection = calimero.create_connection(
    api_url="http://localhost:2428",
    node_name="my-node"
)

# Create client
client = calimero.create_client(connection)

Client Operations​

The client provides comprehensive access to Calimero functionality:

Connection Management​

  • get_api_url(): Get the API URL for this client
  • get_peers_count(): Get the number of connected peers

Application Management​

  • get_application(app_id: str): Get information about a specific application
  • list_applications(): List all available applications
  • install_application(url: str, hash: Optional[str], metadata: Optional[bytes]): Install application from URL
  • install_dev_application(path: str, metadata: Optional[bytes]): Install development application from local path
  • uninstall_application(app_id: str): Uninstall an application

Context Management​

  • get_context(context_id: str): Get information about a specific context
  • list_contexts(): List all available contexts
  • create_context(application_id: str, protocol: str, params: Optional[str]): Create a new context
  • delete_context(context_id: str): Delete a context
  • sync_context(context_id: str): Sync a specific context
  • sync_all_contexts(): Sync all contexts

Context Operations​

  • get_context_storage(context_id: str): Get context storage information
  • get_context_identities(context_id: str): Get identities associated with a context
  • get_context_client_keys(context_id: str): Get client keys for a context
  • invite_to_context(context_id: str, inviter_id: str, invitee_id: str): Invite someone to a context
  • join_context(context_id: str, invitee_id: str, invitation_payload: str): Join a context using invitation
  • update_context_application(context_id: str, application_id: str, executor_public_key: str): Update context application

Function Execution​

  • execute_function(context_id: str, method: str, args: str, executor_public_key: str): Execute a function call via JSON-RPC

Permission Management​

  • grant_permissions(context_id: str, permissions: str): Grant permissions to users in a context
  • revoke_permissions(context_id: str, permissions: str): Revoke permissions from users in a context

Proposal Management​

  • get_proposal(context_id: str, proposal_id: str): Get proposal information
  • get_proposal_approvers(context_id: str, proposal_id: str): Get proposal approvers
  • list_proposals(context_id: str, args: Optional[str]): List proposals in a context

Identity Management​

  • generate_context_identity(): Generate a new context identity

Blob Management​

  • list_blobs(): List all blobs
  • get_blob_info(blob_id: str): Get information about a specific blob
  • delete_blob(blob_id: str): Delete a blob

Alias Management​

  • create_context_identity_alias(context_id: str, alias: str, public_key: str): Create context identity alias
  • create_context_alias(alias: str, context_id: str): Create context alias
  • create_application_alias(alias: str, application_id: str): Create application alias
  • delete_context_alias(alias: str): Delete context alias
  • delete_context_identity_alias(alias: str, context_id: str): Delete context identity alias
  • delete_application_alias(alias: str): Delete application alias
  • list_context_aliases(): List context aliases
  • list_context_identity_aliases(context_id: str): List context identity aliases
  • list_application_aliases(): List application aliases
  • lookup_context_alias(alias: str): Lookup context alias
  • lookup_context_identity_alias(alias: str, context_id: str): Lookup context identity alias
  • lookup_application_alias(alias: str): Lookup application alias
  • resolve_context_alias(alias: str): Resolve context alias
  • resolve_context_identity_alias(alias: str, context_id: str): Resolve context identity alias
  • resolve_application_alias(alias: str): Resolve application alias

Error Handling​

The client provides comprehensive error handling:

import calimero

try:
    result = client.execute_function(
        context_id="context-123",
        method="transfer",
        args='{"amount": 100}',
        executor_public_key="key-123"
    )
except RuntimeError as e:
    print(f"Client error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Development Workflow​

Local Development​

# Clone the repository
git clone https://github.com/calimero-network/calimero-client-py
cd calimero-client-py

# Install in development mode
pip install -e .

# Run tests
pytest

# Run example
python example_usage.py

Building from Source​

# Install maturin
pip install maturin

# Build the package
maturin build --release

# Install the built package
pip install target/wheels/calimero_client_py-*.whl

Installation​

Prerequisites​

Before installing the Python client, ensure you have:

  • Python 3.9+ (3.11+ recommended for best performance).
  • pipx (recommended) or pip package manager.
  • Rust toolchain (only needed for building from source).

The easiest way to install the Python client is from PyPI:

pipx install calimero-client-py
pipx ensurepath

Verify Installation​

# Test the installation
python -c "import calimero; print('Installation successful!')"

# Check version
python -c "import calimero; print(calimero.__version__)"

Create an isolated environment for your project:

# Create virtual environment
python -m venv calimero-env

# Activate virtual environment
# On Windows:
calimero-env\Scripts\activate
# On macOS/Linux:
source calimero-env/bin/activate

# Install the client
pip install calimero-client-py

Alternative: Use pipx for a cleaner installation:

pipx install calimero-client-py
pipx ensurepath

Building from Source​

For development or if you need the latest features:

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install maturin (Python-Rust build tool)
pip install maturin

# Clone and build
git clone https://github.com/calimero-network/calimero-client-py
cd calimero-client-py
maturin build --release
pip install target/wheels/calimero_client_py-*.whl

API Reference​

Connection Management​

import calimero

# Basic connection
connection = calimero.create_connection(
    api_url="http://localhost:2428",
    node_name="my-node"
)

# Create client
client = calimero.create_client(connection)

Client Operations​

The client provides comprehensive access to Calimero functionality:

Connection Management​

  • get_api_url(): Get the API URL for this client
  • get_peers_count(): Get the number of connected peers

Application Management​

  • get_application(app_id: str): Get information about a specific application
  • list_applications(): List all available applications
  • install_application(url: str, hash: Optional[str], metadata: Optional[bytes]): Install application from URL
  • install_dev_application(path: str, metadata: Optional[bytes]): Install development application from local path
  • uninstall_application(app_id: str): Uninstall an application

Context Management​

  • get_context(context_id: str): Get information about a specific context
  • list_contexts(): List all available contexts
  • create_context(application_id: str, protocol: str, params: Optional[str]): Create a new context
  • delete_context(context_id: str): Delete a context
  • sync_context(context_id: str): Sync a specific context
  • sync_all_contexts(): Sync all contexts

Context Operations​

  • get_context_storage(context_id: str): Get context storage information
  • get_context_identities(context_id: str): Get identities associated with a context
  • get_context_client_keys(context_id: str): Get client keys for a context
  • invite_to_context(context_id: str, inviter_id: str, invitee_id: str): Invite someone to a context
  • join_context(context_id: str, invitee_id: str, invitation_payload: str): Join a context using invitation
  • update_context_application(context_id: str, application_id: str, executor_public_key: str): Update context application

Function Execution​

  • execute_function(context_id: str, method: str, args: str, executor_public_key: str): Execute a function call via JSON-RPC

Permission Management​

  • grant_permissions(context_id: str, permissions: str): Grant permissions to users in a context
  • revoke_permissions(context_id: str, permissions: str): Revoke permissions from users in a context

Proposal Management​

  • get_proposal(context_id: str, proposal_id: str): Get proposal information
  • get_proposal_approvers(context_id: str, proposal_id: str): Get proposal approvers
  • list_proposals(context_id: str, args: Optional[str]): List proposals in a context

Identity Management​

  • generate_context_identity(): Generate a new context identity

Blob Management​

  • list_blobs(): List all blobs
  • get_blob_info(blob_id: str): Get information about a specific blob
  • delete_blob(blob_id: str): Delete a blob

Alias Management​

  • create_context_identity_alias(context_id: str, alias: str, public_key: str): Create context identity alias
  • create_context_alias(alias: str, context_id: str): Create context alias
  • create_application_alias(alias: str, application_id: str): Create application alias
  • delete_context_alias(alias: str): Delete context alias
  • delete_context_identity_alias(alias: str, context_id: str): Delete context identity alias
  • delete_application_alias(alias: str): Delete application alias
  • list_context_aliases(): List context aliases
  • list_context_identity_aliases(context_id: str): List context identity aliases
  • list_application_aliases(): List application aliases
  • lookup_context_alias(alias: str): Lookup context alias
  • lookup_context_identity_alias(alias: str, context_id: str): Lookup context identity alias
  • lookup_application_alias(alias: str): Lookup application alias
  • resolve_context_alias(alias: str): Resolve context alias
  • resolve_context_identity_alias(alias: str, context_id: str): Resolve context identity alias
  • resolve_application_alias(alias: str): Resolve application alias

Error Handling​

import calimero

try:
    result = client.execute_function(
        context_id="context-123",
        method="transfer",
        args='{"amount": 100}',
        executor_public_key="key-123"
    )
except RuntimeError as e:
    print(f"Client error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Examples​

Basic Usage​

import calimero

def main():
    # Create a connection
    connection = calimero.create_connection(
        api_url="http://localhost:2428",
        node_name="example-node"
    )

    # Create a client
    client = calimero.create_client(connection)

    # List available contexts
    contexts = client.list_contexts()
    print(f"Found {len(contexts)} contexts")

    # List applications
    apps = client.list_applications()
    print(f"Found {len(apps)} applications")

if __name__ == "__main__":
    main()

Resources​

Getting Help​

Next Steps​

Ready to get started with the Python client?

  1. Follow the Installation section above to set up your environment
  2. Explore the API Reference section to understand available methods
  3. Check out the Examples section for practical usage patterns

The Python client brings the power and performance of Calimero Network to the Python ecosystem, enabling you to build sophisticated decentralized applications with the tools you know and love.

Was this page helpful?
Need some help? Check Support page