# Calimero Client Python Bindings
[](https://badge.fury.io/py/calimero-client-py-bindings)
[](https://pypi.org/project/calimero-client-py-bindings/)
[](https://opensource.org/licenses/MIT)
[](https://docs.calimero.network)
A high-performance Python client library for Calimero Network APIs, built with PyO3 for native Rust integration.
## 🚀 Features
- **High Performance**: Built with Rust and PyO3 for maximum speed and efficiency
- **Full API Coverage**: Complete access to Calimero Network APIs
- **Async Support**: Full async/await support for non-blocking operations
- **Authentication**: Built-in JWT token handling and authentication modes
- **Error Handling**: Python-friendly error types with detailed messages
- **Type Safety**: Full type hints and mypy support
- **CLI Interface**: Command-line tool for quick API interactions
## 📦 Installation
### From PyPI (Recommended)
```bash
pip install calimero-client-py-bindings
```
### From Source
```bash
# Clone the repository
git clone https://github.com/calimero-network/core.git
cd core/crates/client
# Install in development mode
pip install -e .
```
## 🏗️ Building from Source
### Prerequisites
- Rust toolchain (1.70+)
- Python 3.8+
- maturin
### Build Steps
```bash
# Install maturin
pip install maturin
# Build the package
maturin build --features python
# Install the built wheel
pip install target/wheels/calimero_client_py_bindings-*.whl
```
## 🎯 Quick Start
### Basic Usage
```python
import asyncio
from calimero_client_py_bindings import create_connection, create_client
async def main():
# Create a connection to Calimero API
connection = create_connection(
api_url="https://api.calimero.network",
node_name="my-node"
)
# Create a client
client = create_client(connection)
# Check API health
response = await connection.get("/health")
print(f"API Health: {response.status_code}")
# Get supported alias types
alias_types = await client.get_supported_alias_types()
print(f"Supported alias types: {alias_types}")
# Run the async function
asyncio.run(main())
```
### Connection Management
```python
from calimero_client_py_bindings import ConnectionInfo, AuthMode
# Create a connection with authentication
connection = ConnectionInfo(
api_url="https://api.calimero.network",
node_name="my-node"
)
# Check authentication requirements
auth_mode = connection.detect_auth_mode()
print(f"Authentication required: {auth_mode.value}")
# Make HTTP requests
response = await connection.get("/api/v1/status")
data = await connection.post("/api/v1/data", {"key": "value"})
```
### Error Handling
```python
from calimero_client_py_bindings import ClientError
try:
response = await connection.get("/api/v1/protected")
except ClientError as e:
if "Authentication" in str(e):
print("Authentication required")
elif "Network" in str(e):
print("Network error occurred")
else:
print(f"Client error: {e}")
```
## 🖥️ Command Line Interface
The package includes a powerful CLI for quick API interactions:
```bash
# Check API health
calimero-client-py health --api-url https://api.calimero.network
# List supported alias types
calimero-client-py aliases --api-url https://api.calimero.network --node-name my-node
# Make a custom request
calimero-client-py request --method GET --endpoint /api/v1/status --api-url https://api.calimero.network
# Verbose output
calimero-client-py health --api-url https://api.calimero.network --verbose
```
## 📚 API Reference
### Core Functions
- `create_connection(api_url: str, node_name: Optional[str]) -> ConnectionInfo`
- `create_client(connection: ConnectionInfo) -> Client`
### Main Classes
#### ConnectionInfo
- `get(endpoint: str) -> Response`
- `post(endpoint: str, data: dict) -> Response`
- `put(endpoint: str, data: dict) -> Response`
- `delete(endpoint: str) -> Response`
- `detect_auth_mode() -> AuthMode`
#### Client
- `get_supported_alias_types() -> List[str]`
- `resolve_alias(alias: str) -> ResolveResponse`
#### Error Types
- `ClientError`: Base error class with subtypes
- `NetworkError`: Network-related errors
- `AuthenticationError`: Authentication failures
- `StorageError`: Storage operation failures
## 🔧 Development
### Setting up Development Environment
```bash
# Clone and setup
git clone https://github.com/calimero-network/core.git
cd core/crates/client
# Install development dependencies
pip install -e ".[dev,test,docs]"
# Run tests
pytest
# Run linting
black src/
isort src/
flake8 src/
mypy src/
# Run type checking
mypy src/
```
### Testing
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=calimero_client_py_bindings
# Run specific test categories
pytest -m "not slow"
pytest -m integration
pytest -m unit
```
## 📖 Documentation
- [API Reference](https://docs.calimero.network)
- [Examples](https://github.com/calimero-network/core/tree/main/crates/client/src/bindings/python/examples)
- [Contributing Guide](https://github.com/calimero-network/core/blob/main/CONTRIBUTING.md)
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](https://github.com/calimero-network/core/blob/main/CONTRIBUTING.md) for details.
### Development Workflow
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/calimero-network/core/blob/main/LICENSE.md) file for details.
## 🆘 Support
- **Documentation**: [docs.calimero.network](https://docs.calimero.network)
- **Issues**: [GitHub Issues](https://github.com/calimero-network/core/issues)
- **Discussions**: [GitHub Discussions](https://github.com/calimero-network/core/discussions)
- **Email**: team@calimero.network
## 🙏 Acknowledgments
- Built with [PyO3](https://pyo3.rs/) for high-performance Python-Rust integration
- Powered by the Calimero Network team and community
- Thanks to all contributors and users
---
**Made with ❤️ by the Calimero Network team**
Raw data
{
"_id": null,
"home_page": null,
"name": "calimero-client-py-bindings",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Calimero Network <team@calimero.network>",
"keywords": "calimero, blockchain, api, client, web3, distributed-ledger, cryptocurrency, defi",
"author": null,
"author_email": "Calimero Network <team@calimero.network>",
"download_url": "https://files.pythonhosted.org/packages/ec/81/521ee935b94e429eaeb907492152438db8b6f19fc4c432cfd1407526e708/calimero_client_py_bindings-0.1.1.tar.gz",
"platform": null,
"description": "# Calimero Client Python Bindings\n\n[](https://badge.fury.io/py/calimero-client-py-bindings)\n[](https://pypi.org/project/calimero-client-py-bindings/)\n[](https://opensource.org/licenses/MIT)\n[](https://docs.calimero.network)\n\nA high-performance Python client library for Calimero Network APIs, built with PyO3 for native Rust integration.\n\n## \ud83d\ude80 Features\n\n- **High Performance**: Built with Rust and PyO3 for maximum speed and efficiency\n- **Full API Coverage**: Complete access to Calimero Network APIs\n- **Async Support**: Full async/await support for non-blocking operations\n- **Authentication**: Built-in JWT token handling and authentication modes\n- **Error Handling**: Python-friendly error types with detailed messages\n- **Type Safety**: Full type hints and mypy support\n- **CLI Interface**: Command-line tool for quick API interactions\n\n## \ud83d\udce6 Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install calimero-client-py-bindings\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/calimero-network/core.git\ncd core/crates/client\n\n# Install in development mode\npip install -e .\n```\n\n## \ud83c\udfd7\ufe0f Building from Source\n\n### Prerequisites\n\n- Rust toolchain (1.70+)\n- Python 3.8+\n- maturin\n\n### Build Steps\n\n```bash\n# Install maturin\npip install maturin\n\n# Build the package\nmaturin build --features python\n\n# Install the built wheel\npip install target/wheels/calimero_client_py_bindings-*.whl\n```\n\n## \ud83c\udfaf Quick Start\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom calimero_client_py_bindings import create_connection, create_client\n\nasync def main():\n # Create a connection to Calimero API\n connection = create_connection(\n api_url=\"https://api.calimero.network\",\n node_name=\"my-node\"\n )\n \n # Create a client\n client = create_client(connection)\n \n # Check API health\n response = await connection.get(\"/health\")\n print(f\"API Health: {response.status_code}\")\n \n # Get supported alias types\n alias_types = await client.get_supported_alias_types()\n print(f\"Supported alias types: {alias_types}\")\n\n# Run the async function\nasyncio.run(main())\n```\n\n### Connection Management\n\n```python\nfrom calimero_client_py_bindings import ConnectionInfo, AuthMode\n\n# Create a connection with authentication\nconnection = ConnectionInfo(\n api_url=\"https://api.calimero.network\",\n node_name=\"my-node\"\n)\n\n# Check authentication requirements\nauth_mode = connection.detect_auth_mode()\nprint(f\"Authentication required: {auth_mode.value}\")\n\n# Make HTTP requests\nresponse = await connection.get(\"/api/v1/status\")\ndata = await connection.post(\"/api/v1/data\", {\"key\": \"value\"})\n```\n\n### Error Handling\n\n```python\nfrom calimero_client_py_bindings import ClientError\n\ntry:\n response = await connection.get(\"/api/v1/protected\")\nexcept ClientError as e:\n if \"Authentication\" in str(e):\n print(\"Authentication required\")\n elif \"Network\" in str(e):\n print(\"Network error occurred\")\n else:\n print(f\"Client error: {e}\")\n```\n\n## \ud83d\udda5\ufe0f Command Line Interface\n\nThe package includes a powerful CLI for quick API interactions:\n\n```bash\n# Check API health\ncalimero-client-py health --api-url https://api.calimero.network\n\n# List supported alias types\ncalimero-client-py aliases --api-url https://api.calimero.network --node-name my-node\n\n# Make a custom request\ncalimero-client-py request --method GET --endpoint /api/v1/status --api-url https://api.calimero.network\n\n# Verbose output\ncalimero-client-py health --api-url https://api.calimero.network --verbose\n```\n\n## \ud83d\udcda API Reference\n\n### Core Functions\n\n- `create_connection(api_url: str, node_name: Optional[str]) -> ConnectionInfo`\n- `create_client(connection: ConnectionInfo) -> Client`\n\n### Main Classes\n\n#### ConnectionInfo\n- `get(endpoint: str) -> Response`\n- `post(endpoint: str, data: dict) -> Response`\n- `put(endpoint: str, data: dict) -> Response`\n- `delete(endpoint: str) -> Response`\n- `detect_auth_mode() -> AuthMode`\n\n#### Client\n- `get_supported_alias_types() -> List[str]`\n- `resolve_alias(alias: str) -> ResolveResponse`\n\n#### Error Types\n- `ClientError`: Base error class with subtypes\n- `NetworkError`: Network-related errors\n- `AuthenticationError`: Authentication failures\n- `StorageError`: Storage operation failures\n\n## \ud83d\udd27 Development\n\n### Setting up Development Environment\n\n```bash\n# Clone and setup\ngit clone https://github.com/calimero-network/core.git\ncd core/crates/client\n\n# Install development dependencies\npip install -e \".[dev,test,docs]\"\n\n# Run tests\npytest\n\n# Run linting\nblack src/\nisort src/\nflake8 src/\nmypy src/\n\n# Run type checking\nmypy src/\n```\n\n### Testing\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=calimero_client_py_bindings\n\n# Run specific test categories\npytest -m \"not slow\"\npytest -m integration\npytest -m unit\n```\n\n## \ud83d\udcd6 Documentation\n\n- [API Reference](https://docs.calimero.network)\n- [Examples](https://github.com/calimero-network/core/tree/main/crates/client/src/bindings/python/examples)\n- [Contributing Guide](https://github.com/calimero-network/core/blob/main/CONTRIBUTING.md)\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](https://github.com/calimero-network/core/blob/main/CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Run the test suite\n6. Submit a pull request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/calimero-network/core/blob/main/LICENSE.md) file for details.\n\n## \ud83c\udd98 Support\n\n- **Documentation**: [docs.calimero.network](https://docs.calimero.network)\n- **Issues**: [GitHub Issues](https://github.com/calimero-network/core/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/calimero-network/core/discussions)\n- **Email**: team@calimero.network\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [PyO3](https://pyo3.rs/) for high-performance Python-Rust integration\n- Powered by the Calimero Network team and community\n- Thanks to all contributors and users\n\n---\n\n**Made with \u2764\ufe0f by the Calimero Network team**\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client library for Calimero Network - a comprehensive blockchain API client",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/calimero-network/core/issues",
"Changelog": "https://github.com/calimero-network/core/blob/main/CHANGELOG.md",
"Discussions": "https://github.com/calimero-network/core/discussions",
"Documentation": "https://docs.calimero.network",
"Homepage": "https://calimero.network",
"Repository": "https://github.com/calimero-network/core"
},
"split_keywords": [
"calimero",
" blockchain",
" api",
" client",
" web3",
" distributed-ledger",
" cryptocurrency",
" defi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1b526732ca86ddd48836d272f2d716c4a1162409e31c5d7a72168ed36ab1b32b",
"md5": "b2cbed5914884cc0b35eb821abe56d38",
"sha256": "b93165d7a24e54078e671af643a8248434c871c0c5e06256d1ed22234a594cb3"
},
"downloads": -1,
"filename": "calimero_client_py_bindings-0.1.1-cp313-cp313-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "b2cbed5914884cc0b35eb821abe56d38",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.8",
"size": 1295021,
"upload_time": "2025-08-28T13:48:47",
"upload_time_iso_8601": "2025-08-28T13:48:47.025019Z",
"url": "https://files.pythonhosted.org/packages/1b/52/6732ca86ddd48836d272f2d716c4a1162409e31c5d7a72168ed36ab1b32b/calimero_client_py_bindings-0.1.1-cp313-cp313-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ec81521ee935b94e429eaeb907492152438db8b6f19fc4c432cfd1407526e708",
"md5": "4823269aaff1a31fd3c9f06b390570e5",
"sha256": "21626ff7f49c2ad5b324e9e4e2ac4798db3f9b566a8d95bfdcb3bed174486fb3"
},
"downloads": -1,
"filename": "calimero_client_py_bindings-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4823269aaff1a31fd3c9f06b390570e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 246120,
"upload_time": "2025-08-28T13:48:49",
"upload_time_iso_8601": "2025-08-28T13:48:49.005705Z",
"url": "https://files.pythonhosted.org/packages/ec/81/521ee935b94e429eaeb907492152438db8b6f19fc4c432cfd1407526e708/calimero_client_py_bindings-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 13:48:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "calimero-network",
"github_project": "core",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "calimero-client-py-bindings"
}
JSON
