calimero-client-py 0.2.3

Python client SDK for Calimero Network

Calimero Client Python Library

A comprehensive Python client library for Calimero Network APIs, built with PyO3 for high performance and native integration.

Features

• High Performance: Built with Rust and PyO3 for optimal performance
• Comprehensive API: Full access to Calimero Network functionality
• Type Safety: Strongly typed Python bindings
• Async Support: Built-in async/await support
• Easy Installation: Simple pip install

Supported Protocols

• ✅ NEAR Protocol
• ✅ Ethereum
• ✅ Internet Computer Protocol (ICP)
• ✅ Starknet
• ❌ Stellar (removed)

Quick Start

import asyncio
from calimero_client_py import create_connection, create_client, AuthMode

async def main():
    # Create a connection
    connection = create_connection(
        base_url="http://localhost:2528",
        auth_mode=AuthMode.NONE
    )
    
    # Create a client
    client = create_client(connection)
    
    # Use the client
    contexts = await client.list_contexts()
    print(f"Found {len(contexts)} contexts")

if __name__ == "__main__":
    asyncio.run(main())

Installation

pip install calimero-client-py

Development

Building from Source

# Install dependencies
pip install maturin

# Build the package
maturin build --release

# Install in development mode
maturin develop

Running Tests

python scripts/run_tests.py

🏗️ Project Structure

calimero-client-py/
├── README.md                    # This file
├── LICENSE                      # License file
├── pyproject.toml              # Python package configuration
├── Cargo.toml                  # Rust package configuration
├── Cargo.lock                  # Rust lock file
├── .github/
│   └── workflows/              # CI/CD workflows
├── src/                        # Rust source code
│   ├── lib.rs
│   ├── mod.rs
│   └── python.rs
├── calimero_client_py/         # Python package
│   ├── __init__.py
│   └── cli.py
├── tests/                      # All tests
│   ├── test_integration.py
│   └── conftest.py
└── scripts/                    # Build and utility scripts
    ├── build.sh
    └── run_tests.py

🚀 Build Status

Current Status: ✅ Ready to Build

The Python bindings for calimero-client are ready to build. Stellar support has been removed from the codebase.

Environment Setup: ✅ Complete

• Python Version: 3.13.7
• Virtual Environment: ✅ Active and working
• Maturin: ✅ Installed (version 1.9.4)
• PyO3: ✅ Version 0.20.3 (compatible with Python 3.13 via ABI3)

Current Working Components

• ✅ Python 3.13 virtual environment
• ✅ Maturin build system
• ✅ PyO3 configuration
• ✅ Basic project structure
• ✅ Rust toolchain
• ✅ All supported protocol dependencies

🔧 Building

From the Repository Root (Recommended)

# From calimero-client-py root directory
./scripts/build.sh

# Or with options
./scripts/build.sh --install  # Build and install in development mode

Manual Build

# Install maturin if you haven't already
pip install maturin

# Build the wheel
maturin build --release

# Install in development mode
maturin develop --release

Standalone Build

This package can be built independently without requiring the full Calimero workspace.

Prerequisites

• Rust toolchain (1.70+)
• Python 3.8+
• maturin (will be installed automatically if missing)

Benefits of Standalone Build

✅ Independent builds - No need for full workspace
✅ Easier distribution - Can be built anywhere
✅ CI/CD friendly - Simpler build pipelines
✅ Version control - Clear dependency management
✅ Faster builds - Only builds what's needed

📦 Dependencies

The bindings depend on these crates (published to crates.io):

• calimero-client - Core client functionality
• calimero-primitives - Core data types

🧪 Testing

# Test Rust code
cargo test

# Test Python integration
python scripts/run_tests.py

# Test the environment
source venv/bin/activate.fish
python test-python.py

📤 Publishing to PyPI

This guide explains how to publish the calimero-client-py package to PyPI and other Python package repositories.

Prerequisites

1. PyPI Account

• Create an account on PyPI
• Enable two-factor authentication (2FA) for security
• Create an API token for automated publishing

2. Test PyPI Account (Recommended)

• Create an account on Test PyPI
• Use this for testing before publishing to production

3. Required Tools

# Install publishing tools
pip install twine build

# Install maturin for Rust bindings
pip install maturin

Building the Package

1. Clean Build Environment

# Remove previous builds
rm -rf target/wheels/
rm -rf dist/
rm -rf build/
rm -rf *.egg-info/

2. Build with Maturin

# Build the Python wheel
maturin build --features python --release

# Verify the wheel was created
ls -la target/wheels/

3. Build Source Distribution (Optional)

# Build source distribution
python -m build --sdist

# Verify source distribution
ls -la dist/

Testing Before Publishing

1. Test Installation

# Install from wheel
pip install target/wheels/calimero_client_py-*.whl

# Test import
python -c "import calimero_client_py; print('Import successful')"

# Test CLI
calimero-client-py --help

2. Test on Test PyPI

# Upload to Test PyPI
twine upload --repository testpypi target/wheels/*.whl

# Install from Test PyPI
pip install --index-url https://test.pypi.org/simple/ calimero-client-py

# Test functionality
python -c "import calimero_client_py; print('Test PyPI install successful')"

Publishing to PyPI

1. Final Verification

# Check package metadata
twine check target/wheels/*.whl

# Verify package contents
pip show calimero-client-py

2. Upload to PyPI

# Upload to production PyPI
twine upload target/wheels/*.whl

# Or upload both wheel and source
twine upload dist/*

3. Verify Publication

# Wait a few minutes for PyPI to update
# Check on https://pypi.org/project/calimero-client-py/

# Test installation from PyPI
pip install calimero-client-py

# Verify it works
python -c "import calimero_client_py; print('PyPI install successful')"

Automated Publishing with GitHub Actions

The package includes a GitHub Actions workflow that automatically publishes when you create a release tag.

1. Create a Release

# Tag the release
git tag -a v0.1.0 -m "Release version 0.1.0"

# Push the tag
git push origin v0.1.0

2. Set Up Secrets

In your GitHub repository settings, add these secrets:

• PYPI_API_TOKEN: Your PyPI API token
• TEST_PYPI_API_TOKEN: Your Test PyPI API token (optional)

3. Monitor the Workflow

• Check the Actions tab in GitHub
• The workflow will automatically:
  • Build the package
  • Run tests
  • Publish to PyPI

Common Issues and Solutions

1. Build Failures

# Check Rust toolchain
rustup show

# Update dependencies
cargo update

# Clean and rebuild
cargo clean
maturin build --features python

2. Import Errors

# Verify module structure
python -c "import sys; print(sys.path)"

# Check package installation
pip list | grep calimero

3. PyPI Upload Errors

# Check authentication
twine check target/wheels/*.whl

# Verify API token
echo $PYPI_API_TOKEN

# Test with Test PyPI first
twine upload --repository testpypi target/wheels/*.whl

Maintenance

1. Version Management

# Update version in all files:
# - pyproject.toml
# - Cargo.toml
# - calimero_client_py/__init__.py
# - README.md (if version is mentioned)

2. Dependency Updates

# Update Rust dependencies
cargo update

# Update Python dependencies
pip install --upgrade -r requirements-dev.txt

# Test with updated dependencies
pytest

3. Security Updates

# Check for security vulnerabilities
safety check

# Update vulnerable packages
pip install --upgrade package-name

Troubleshooting

• Build fails: Make sure calimero-client is published to crates.io
• Import errors: Verify the wheel was built for your Python version
• Runtime errors: Check that all dependencies are properly linked

Additional Resources

• PyPI Packaging Guide
• Maturin Documentation
• Twine Documentation
• Python Packaging Authority

API Reference

Core Classes

• Client: Main client for interacting with Calimero Network
• ConnectionInfo: Connection configuration
• JwtToken: JWT authentication token
• ClientError: Error handling
• AuthMode: Authentication modes

Main Functions

• create_connection(): Create a new connection
• create_client(): Create a new client instance

Client Methods

The Client class provides comprehensive access to Calimero Network 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

Response Format

All client methods return Python objects (dictionaries, lists, etc.) containing the response data. The exact structure depends on the specific method called, but generally follows these patterns:

Success Response

{
    "success": True,
    "data": { ... },  # Method-specific data
    "message": "Operation completed successfully"
}

Error Response

{
    "success": False,
    "error": "Error description",
    "error_type": "Network|Authentication|Storage|Internal"
}

Example Usage

import asyncio
from calimero_client_py import create_connection, create_client, AuthMode

async def main():
    # Create connection
    connection = create_connection(
        base_url="http://localhost:2528",
        auth_mode=AuthMode.NONE
    )
    
    # Create client
    client = create_client(connection)
    
    # List applications
    apps = client.list_applications()
    print(f"Found {len(apps)} applications")
    
    # Create a context
    context = client.create_context(
        application_id="my-app-id",
        protocol="near",
        params='{"network": "testnet"}'
    )
    print(f"Created context: {context}")
    
    # Execute a function
    result = client.execute_function(
        context_id=context["context_id"],
        method="set_value",
        args='{"key": "test", "value": "hello"}',
        executor_public_key="your-public-key"
    )
    print(f"Function result: {result}")

if __name__ == "__main__":
    asyncio.run(main())

Support

If you encounter issues during publishing:

1. Check the GitHub Issues
2. Review the GitHub Actions logs
3. Contact the team at [e-mail]

---

Happy Publishing! 🎉