calimero-client-py 0.1.1__tar.gz

calimero_client_py-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Calimero Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

calimero_client_py-0.1.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: calimero-client-py
+Version: 0.1.1
+Summary: Python client SDK for Calimero Network
+Home-page: https://github.com/calimero-network/calimero-client-py
+Author: Calimero Network
+Author-email: Calimero Network <support@calimero.network>
+License: MIT
+Project-URL: Homepage, https://github.com/calimero-network/calimero-client-py
+Project-URL: Documentation, https://docs.calimero.network/python-sdk
+Project-URL: Repository, https://github.com/calimero-network/calimero-client-py
+Project-URL: Issues, https://github.com/calimero-network/calimero-client-py/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: base58>=2.1.1
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: pynacl>=1.5.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Calimero Network Python Client SDK
+
+The **Calimero Python Client SDK** helps developers interact with decentralized apps by handling server communication. It simplifies the process, letting you focus on building your app while the SDK manages the technical details.
+
+## Features
+
+- JSON-RPC client for sending queries and updates to Calimero nodes
+- WebSocket client for real-time subscriptions
+- Authentication handling with Ed25519 keypairs
+- Configuration management
+- Type hints and comprehensive documentation
+
+## Installation
+
+```bash
+pip install calimero-client-py
+```
+
+## Quick Start
+
+### Using JsonRpcClient
+
+```python
+from calimero import JsonRpcClient
+
+client = JsonRpcClient(
+    base_url="http://localhost:2428",
+    endpoint="/jsonrpc"
+)
+
+params = {
+    "applicationId": "your_application_id",
+    "method": "create_post",
+    "argsJson": {"title": "My First Post", "text": "This is my first post"}
+}
+
+response = await client.mutate(params)
+print(response)
+```
+
+### Using WsSubscriptionsClient
+
+```python
+from calimero import WsSubscriptionsClient
+
+client = WsSubscriptionsClient(
+    base_url="http://localhost:2428",
+    endpoint="/ws"
+)
+
+await client.connect()
+client.subscribe(["your_application_id"])
+
+def callback(data):
+    print(data)
+
+client.add_callback(callback)
+```
+
+## Documentation
+
+For detailed documentation, please visit [our documentation site](https://docs.calimero.network).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. 
+
+## Test Dependencies and Commands
+
+To run tests, you need to install the test dependencies and then run the tests.
+
+```bash
+# Install test dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=calimero
+
+# Run specific test file
+pytest tests/test_keypair.py
+``` 

calimero_client_py-0.1.1/README.md

@@ -0,0 +1,84 @@
+# Calimero Network Python Client SDK
+
+The **Calimero Python Client SDK** helps developers interact with decentralized apps by handling server communication. It simplifies the process, letting you focus on building your app while the SDK manages the technical details.
+
+## Features
+
+- JSON-RPC client for sending queries and updates to Calimero nodes
+- WebSocket client for real-time subscriptions
+- Authentication handling with Ed25519 keypairs
+- Configuration management
+- Type hints and comprehensive documentation
+
+## Installation
+
+```bash
+pip install calimero-client-py
+```
+
+## Quick Start
+
+### Using JsonRpcClient
+
+```python
+from calimero import JsonRpcClient
+
+client = JsonRpcClient(
+    base_url="http://localhost:2428",
+    endpoint="/jsonrpc"
+)
+
+params = {
+    "applicationId": "your_application_id",
+    "method": "create_post",
+    "argsJson": {"title": "My First Post", "text": "This is my first post"}
+}
+
+response = await client.mutate(params)
+print(response)
+```
+
+### Using WsSubscriptionsClient
+
+```python
+from calimero import WsSubscriptionsClient
+
+client = WsSubscriptionsClient(
+    base_url="http://localhost:2428",
+    endpoint="/ws"
+)
+
+await client.connect()
+client.subscribe(["your_application_id"])
+
+def callback(data):
+    print(data)
+
+client.add_callback(callback)
+```
+
+## Documentation
+
+For detailed documentation, please visit [our documentation site](https://docs.calimero.network).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. 
+
+## Test Dependencies and Commands
+
+To run tests, you need to install the test dependencies and then run the tests.
+
+```bash
+# Install test dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=calimero
+
+# Run specific test file
+pytest tests/test_keypair.py
+``` 

calimero_client_py-0.1.1/calimero/__init__.py

@@ -0,0 +1,19 @@
+"""
+Calimero Network Python Client SDK
+"""
+
+__version__ = "0.1.0"
+
+from .config import Config, ConfigError
+from .keypair import Ed25519Keypair, KeypairError
+from .json_rpc_client import JsonRpcClient
+from .ws_subscriptions_client import WsSubscriptionsClient
+
+__all__ = [
+    'Config',
+    'ConfigError',
+    'Ed25519Keypair',
+    'KeypairError',
+    'JsonRpcClient',
+    'WsSubscriptionsClient'
+] 

calimero_client_py-0.1.1/calimero/config.py

@@ -0,0 +1,104 @@
+import os
+from pathlib import Path
+from typing import Optional, Dict, Any
+import toml
+from pydantic import BaseModel, ConfigDict
+from .keypair import Ed25519Keypair
+
+class IdentityConfig(BaseModel):
+    peer_id: str
+    keypair: str
+
+class SwarmConfig(BaseModel):
+    listen: list[str]
+
+class ServerConfig(BaseModel):
+    listen: list[str]
+    admin: Dict[str, bool]
+    jsonrpc: Dict[str, bool]
+    websocket: Dict[str, bool]
+
+class ConfigError(Exception):
+    """Exception raised for configuration-related errors."""
+    pass
+
+class Config:
+    """Configuration for Calimero client."""
+    
+    def __init__(self, file_path: str):
+        """Initialize with a TOML file path."""
+        self._config_data = self._load_toml(file_path)
+        
+        # Load keypair
+        keypair_value = self._config_data.get('identity', {}).get('keypair')
+        if not keypair_value:
+            raise ConfigError("'keypair' not found in [identity] section")
+        self.keypair = Ed25519Keypair.from_base58(keypair_value)
+        
+        # Load network configuration
+        network = self._config_data.get('network', {})
+        self.node_url = network.get('rpc_url')
+        self.context_id = network.get('context_id')
+        self.executor_public_key = network.get('executor_public_key')
+        self.node_name = network.get('node_name')
+        
+        # Validate required fields
+        if not self.node_url:
+            raise ConfigError("'rpc_url' not found in [network] section")
+        if not self.context_id:
+            raise ConfigError("'context_id' not found in [network] section")
+        if not self.executor_public_key:
+            raise ConfigError("'executor_public_key' not found in [network] section")
+        if not self.node_name:
+            raise ConfigError("'node_name' not found in [network] section")
+    
+    def __getitem__(self, key: str) -> Any:
+        """Allow dynamic access to raw config data."""
+        return self._config_data[key]
+    
+    def __getattr__(self, name: str) -> Any:
+        """Allow dynamic access to config sections."""
+        if name in self._config_data:
+            return self._config_data[name]
+        raise AttributeError(f"'Config' object has no attribute '{name}'")
+    
+    @classmethod
+    def load_from_file(cls, file_path: str) -> 'Config':
+        """Load configuration from a TOML file."""
+        return cls(file_path)
+    
+    @classmethod
+    def get_default_config_path(cls) -> Path:
+        """Get the default configuration path."""
+        node_name = os.getenv('CALIMERO_NODE_NAME', 'node1')
+        return Path.home() / '.calimero' / node_name / 'config.toml'
+    
+    def _load_toml(self, file_path: str) -> dict:
+        """Load and parse TOML file."""
+        try:
+            with open(file_path, 'r') as f:
+                return toml.load(f)
+        except Exception as e:
+            raise ConfigError(f"Failed to load config file: {str(e)}")
+    
+    @classmethod
+    def load_from_env(cls) -> 'Config':
+        """Load configuration from environment variables."""
+        import tempfile
+        
+        # Create temporary TOML file
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.toml', delete=False) as f:
+            config_data = {
+                'identity': {
+                    'keypair': os.getenv('CALIMERO_KEYPAIR')
+                },
+                'network': {
+                    'rpc_url': os.getenv('RPC_URL', 'http://localhost:2428'),
+                    'context_id': os.getenv('CONTEXT_ID'),
+                    'executor_public_key': os.getenv('EXECUTOR_PUBLIC_KEY'),
+                    'node_name': os.getenv('CALIMERO_NODE_NAME')
+                }
+            }
+            toml.dump(config_data, f)
+            f.flush()
+            return cls(f.name) 

calimero_client_py-0.1.1/calimero/json_rpc_client.py

@@ -0,0 +1,153 @@
+import asyncio
+import os
+import time
+import base58
+import json
+from typing import Optional, Dict, Any, TypedDict
+import aiohttp
+from .config import Config
+from .keypair import Ed25519Keypair
+
+class JsonRpcError(Exception):
+    """Base exception for JSON-RPC errors."""
+    pass
+
+class JsonRpcResponse(TypedDict):
+    """Type definition for JSON-RPC response."""
+    jsonrpc: str
+    id: int
+    result: Optional[Dict[str, Any]]
+    error: Optional[Dict[str, Any]]
+
+class JsonRpcClient:
+    """JSON-RPC client for Calimero.
+    
+    This client handles communication with the Calimero JSON-RPC server,
+    including request formatting, signing, and response handling.
+    """
+    
+    # Constants
+    JSONRPC_VERSION = '2.0'
+    DEFAULT_TIMEOUT = 1000
+    JSONRPC_PATH = '/jsonrpc/dev'
+    
+    def __init__(self, config: Config):
+        """Initialize the JSON-RPC client with a config.
+        
+        Args:
+            config: Configuration object containing node URL and keypair.
+            
+        Raises:
+            ValueError: If required environment variables are not set.
+        """
+        self.config = config
+        self.node_url = config.node_url
+        self.keypair = config.keypair
+        self.context_id = os.getenv('CONTEXT_ID')
+        self.executor_public_key = os.getenv('EXECUTOR_PUBLIC_KEY')
+        
+        self._validate_environment()
+    
+    def _validate_environment(self) -> None:
+        """Validate that required environment variables are set.
+        
+        Raises:
+            ValueError: If any required environment variable is missing.
+        """
+        if not self.context_id:
+            raise ValueError("CONTEXT_ID environment variable is not set")
+        if not self.executor_public_key:
+            raise ValueError("EXECUTOR_PUBLIC_KEY environment variable is not set")
+    
+    def _prepare_headers(self) -> Dict[str, str]:
+        """Prepare request headers with signature and timestamp.
+        
+        Returns:
+            Dictionary containing request headers.
+        """
+        timestamp = str(int(time.time()))
+        signature = self.keypair.sign(timestamp.encode())
+        signature_b58 = base58.b58encode(signature).decode()
+        
+        return {
+            'Content-Type': 'application/json',
+            'X-Signature': signature_b58,
+            'X-Timestamp': timestamp
+        }
+    
+    def _prepare_request(self, method: str, args: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Prepare the JSON-RPC request payload.
+        
+        Args:
+            method: The method to call.
+            args: Optional arguments for the method.
+            
+        Returns:
+            Dictionary containing the JSON-RPC request payload.
+        """
+        return {
+            'jsonrpc': self.JSONRPC_VERSION,
+            'id': 1,
+            'method': 'execute',
+            'params': {
+                'contextId': self.context_id,
+                'method': method,
+                'argsJson': args or {},
+                'executorPublicKey': self.executor_public_key,
+                'timeout': self.DEFAULT_TIMEOUT
+            }
+        }
+    
+    async def _handle_response(self, response: aiohttp.ClientResponse) -> JsonRpcResponse:
+        """Handle the JSON-RPC response.
+        
+        Args:
+            response: The HTTP response from the server.
+            
+        Returns:
+            Parsed JSON-RPC response.
+            
+        Raises:
+            JsonRpcError: If the response indicates an error.
+        """
+        if response.status != 200:
+            error_text = await response.text()
+            raise JsonRpcError(f"HTTP error {response.status}: {error_text}")
+        
+        result = await response.json()
+        if os.getenv('VERBOSE') == '1':
+            print(f"Result: {json.dumps(result, indent=2)}")
+            
+        if 'error' in result:
+            raise JsonRpcError(f"JSON-RPC error: {result['error']}")
+            
+        return result
+    
+    async def execute(self, method: str, args: Optional[Dict[str, Any]] = None) -> JsonRpcResponse:
+        """Execute a JSON-RPC request.
+        
+        Args:
+            method: The method to call.
+            args: Optional arguments for the method.
+            
+        Returns:
+            Parsed JSON-RPC response.
+            
+        Raises:
+            JsonRpcError: If the request fails or returns an error.
+        """
+        headers = self._prepare_headers()
+        payload = self._prepare_request(method, args)
+        
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    f"{self.node_url}{self.JSONRPC_PATH}",
+                    headers=headers,
+                    json=payload
+                ) as response:
+                    return await self._handle_response(response)
+        except aiohttp.ClientError as e:
+            raise JsonRpcError(f"Network error: {str(e)}")
+        except json.JSONDecodeError as e:
+            raise JsonRpcError(f"Invalid JSON response: {str(e)}") 

calimero_client_py-0.1.1/calimero/keypair.py

@@ -0,0 +1,111 @@
+import base58
+from typing import Tuple
+import nacl.signing
+import nacl.encoding
+from typing import Optional
+
+class KeypairError(Exception):
+    """Exception raised for keypair-related errors."""
+    pass
+
+class Ed25519Keypair:
+    """Ed25519 keypair implementation."""
+    
+    PROTOBUF_PREFIX = b'\x08\x01\x12\x40'  # 4-byte protobuf prefix for Ed25519 keypair
+
+    def __init__(self, signing_key: nacl.signing.SigningKey):
+        """Initialize with a PyNaCl signing key."""
+        self._signing_key = signing_key
+        self._verify_key = signing_key.verify_key
+
+    @classmethod
+    def from_base58(cls, base58_keypair: str) -> 'Ed25519Keypair':
+        """Create a keypair from a base58-encoded keypair string."""
+        if not base58_keypair:
+            raise KeypairError("Base58 keypair cannot be None")
+
+        try:
+            # Decode base58
+            key_bytes = base58.b58decode(base58_keypair)
+
+            # Validate keypair length (should be 68 bytes: 4-byte prefix + 64-byte keypair)
+            if len(key_bytes) != 68:
+                raise KeypairError(f"Unexpected keypair length: {len(key_bytes)} bytes (expected 68)")
+
+            # Validate protobuf prefix
+            prefix = key_bytes[:4]
+            if prefix != cls.PROTOBUF_PREFIX:
+                raise KeypairError(f"Invalid protobuf prefix: {prefix.hex()} (expected {cls.PROTOBUF_PREFIX.hex()})")
+
+            # Extract private key (first 32 bytes after prefix)
+            private_key = key_bytes[4:36]
+            if len(private_key) != 32:
+                raise KeypairError(f"Invalid private key length: {len(private_key)} (expected 32)")
+
+            # Create signing key from private key
+            signing_key = nacl.signing.SigningKey(private_key)
+            return cls(signing_key)
+
+        except Exception as e:
+            raise KeypairError(f"Failed to create keypair: {str(e)}")
+
+    def to_base58(self) -> str:
+        """Convert keypair to base58-encoded string with protobuf prefix."""
+        # Get the private key bytes
+        private_key = self._signing_key.encode()
+        
+        # Create the full keypair bytes with protobuf prefix
+        keypair_bytes = self.PROTOBUF_PREFIX + private_key
+        
+        # Encode to base58
+        return base58.b58encode(keypair_bytes).decode()
+
+    def sign(self, message: bytes) -> bytes:
+        """Sign a message."""
+        return self._signing_key.sign(message).signature
+
+    def verify(self, message: bytes, signature: bytes) -> bool:
+        """Verify a signature."""
+        try:
+            self._verify_key.verify(message, signature)
+            return True
+        except nacl.exceptions.BadSignatureError:
+            return False
+
+    def get_public_key(self) -> bytes:
+        """Get the public key."""
+        return self._verify_key.encode()
+
+    def get_public_key_base58(self) -> str:
+        """Get the public key as base58-encoded string."""
+        return base58.b58encode(self.get_public_key()).decode()
+
+    @property
+    def public_key(self) -> bytes:
+        """Get the public key in raw bytes."""
+        return self._verify_key.encode()
+    
+    @property
+    def public_key_b58(self) -> str:
+        """Get the public key in base58 format."""
+        return base58.b58encode(self.public_key).decode()
+    
+    @property
+    def private_key(self) -> bytes:
+        """Get the private key."""
+        return self._signing_key.encode()
+
+    @property
+    def private_key_base58(self) -> str:
+        """Get the base58-encoded private key."""
+        return base58.b58encode(self.private_key).decode()
+
+    def sign_base58(self, message: str) -> str:
+        """Sign a message and return base58-encoded signature."""
+        signature = self.sign(message.encode())
+        return base58.b58encode(signature).decode()
+
+    def verify_base58(self, message: str, base58_signature: str) -> bool:
+        """Verify a base58-encoded signature."""
+        signature = base58.b58decode(base58_signature)
+        return self.verify(message.encode(), signature)