Zenoo RPC¶

A zen-like, modern async Python library for Odoo RPC with type safety and superior Developer Experience (DX)

🚀 Why Zenoo RPC?¶

Zenoo RPC is a next-generation Python library designed to replace odoorpc with modern Python practices and superior performance. Built from the ground up with async/await, type safety, and developer experience in mind.

✨ Key Features¶

🔄 Async-First: Built with asyncio and httpx for high-performance concurrent operations
🛡️ Type Safety: Full Pydantic integration with IDE support and runtime validation
🎯 Fluent API: Intuitive, chainable query builder that feels natural
⚡ Performance: Intelligent caching, batch operations, and optimized RPC calls
🔧 Modern Python: Leverages Python 3.8+ features with proper type hints
📦 Clean Architecture: Well-structured, testable, and maintainable codebase
🔄 Transaction Support: ACID-compliant transactions with rollback capabilities
🚀 Batch Operations: Efficient bulk operations for high-performance scenarios
🔁 Retry Mechanisms: Intelligent retry with exponential backoff and circuit breaker
💾 Intelligent Caching: TTL/LRU caching with Redis support

🤔 Problems with odoorpc¶

Synchronous only: No async support for modern Python applications
No type safety: Raw dictionaries and lists without validation
Chatty API: Multiple RPC calls for simple operations (search + browse)
Complex relationship handling: Requires knowledge of Odoo's tuple commands
Poor error handling: Generic exceptions without context
No caching: Repeated calls for the same data
No transactions: No rollback capabilities
No batch operations: Inefficient for bulk operations

🎯 Zenoo RPC Solutions¶

# odoorpc (old way)
Partner = odoo.env['res.partner']
partner_ids = Partner.search([('is_company', '=', True)], limit=10)
partners = Partner.browse(partner_ids)  # Second RPC call!

# Zenoo RPC (modern way)
partners = await client.model(ResPartner).filter(
    is_company=True
).limit(10).all()  # Single RPC call with type safety!

🚀 Quick Start¶

Installation¶

pip install zenoo-rpc

For development with all optional dependencies:

pip install zenoo-rpc[dev,redis]

Basic Usage¶

import asyncio
from zenoo_rpc import ZenooClient
from zenoo_rpc.models.common import ResPartner

async def main():
    async with ZenooClient("https://your-odoo-server.com") as client:
        # Authenticate
        await client.login("your_database", "your_username", "your_password")

        # Type-safe queries with IDE support
        partners = await client.model(ResPartner).filter(
            is_company=True,
            name__ilike="company%"
        ).limit(10).all()

        # Access fields with full type safety
        for partner in partners:
            print(f"Company: {partner.name} - Email: {partner.email}")

        # Transaction management
        async with client.transaction() as tx:
            partner = await client.model(ResPartner).get(1)
            partner.name = "New Name"
            partner.email = "new@email.com"
            # Committed automatically on context exit

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

📚 Documentation Sections¶

🏁 Getting Started¶

Installation Guide - Complete installation instructions
Quick Start Tutorial - Get up and running in 5 minutes
Migration from odoorpc - Step-by-step migration guide

📖 User Guide¶

Client Usage - ZenooClient configuration and usage
Models & Type Safety - Pydantic models and validation
Query Builder - Fluent queries and Q objects
Relationships - Lazy loading and relationships
Caching System - Intelligent caching strategies
Transactions - ACID transactions and rollback
Batch Operations - Efficient bulk operations
Retry Mechanisms - Resilient error handling
Error Handling - Exception hierarchy and debugging

🎓 Tutorials¶

Basic CRUD Operations - Create, read, update, delete
Advanced Queries - Complex filtering and joins
Performance Optimization - Speed up your code
Testing Strategies - Test your Odoo integrations
Production Deployment - Deploy with confidence

📋 Examples¶

Real-World Examples - Production-ready code samples
Common Patterns - Reusable patterns and recipes
Integration Examples - FastAPI, Django, Flask integrations

🔧 API Reference¶

Complete API Documentation - Auto-generated API reference

🏗️ Advanced Topics¶

Architecture Overview - Internal design and patterns
Performance Considerations - Optimization techniques
Security Best Practices - Secure your integrations
Extending Zenoo RPC - Custom models and transports

🔍 Troubleshooting¶

Common Issues - Solutions to frequent problems
Debugging Guide - Debug your integrations
FAQ - Frequently asked questions

🤝 Contributing¶

Development Setup - Set up your dev environment
Testing Guidelines - Write and run tests
Documentation Guidelines - Improve the docs

🏗️ Architecture¶

Zenoo RPC follows modern Python best practices with a clean, modular architecture:

src/zenoo_rpc/
├── client.py              # Main async client
├── transport/             # HTTP transport layer
├── models/                # Pydantic models
├── query/                 # Fluent query builder
├── cache/                 # Async caching layer
├── exceptions/            # Structured exception hierarchy
├── transaction/           # Transaction management
├── batch/                 # Batch operations
├── retry/                 # Retry mechanisms
└── utils/                 # Utilities and helpers

🧪 Development Status¶

Zenoo RPC is currently in Alpha stage. The core architecture is implemented and functional, but the API may change before the stable release.

Roadmap¶

Phase 1: Core transport layer and async client
Phase 2: Pydantic models and query builder foundation
Phase 3: Advanced features (caching, transactions, batch ops)
Phase 4: Documentation and community adoption
Phase 5: Stable release and ecosystem growth

🤝 Contributing¶

We welcome contributions! Please see our Contributing Guide for details.

📄 License¶

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments¶

Inspired by the need to modernize the Odoo Python ecosystem
Built on the shoulders of giants: httpx, pydantic, and asyncio
Thanks to the OCA team for maintaining odoorpc and showing us what to improve

Zenoo RPC: Because your Odoo integrations deserve modern Python! 🐍✨