managerodooapi 0.2.0
Una librería completa para Odoo con capacidades avanzadas de exploración de relaciones y gestión de datos
License: MIT
Requires Python: >=3.8
Keywords: odoo, erp, xmlrpc, api, connector, business

# Manager Odoo API

Una librería de Python completa y fácil de usar para gestionar conexiones y operaciones con Odoo a través de XML-RPC.

## 🚀 Características Principales

- **Conexión sencilla**: Conecta a cualquier instancia de Odoo con credenciales simples
- **Operaciones CRUD completas**: Create, Read, Update, Delete en cualquier modelo
- **Soporte multi-compañía**: Trabaja con múltiples compañías en la misma instancia
- **Integración con pandas**: Crea registros masivos desde DataFrames
- **Upsert inteligente**: Crea o actualiza registros basado en IDs externos
- **Validación robusta**: Manejo de errores y validación de datos
- **Type hints**: Código completamente tipado para mejor desarrollo

## 📦 Instalación

```bash
pip install managerodooapi
```

## 🔧 Uso Básico

### Configuración inicial

```python
from managerodooapi import OdooConnector, Credentials

# Configurar credenciales
creds = Credentials(
    url="http://localhost:8069",
    db="mi_base_de_datos",
    username="admin",
    password="admin"
)

# Crear conector (se conecta automáticamente)
odoo = OdooConnector(creds)
```

### Operaciones básicas

```python
# Buscar registros
partner_ids = odoo.search('res.partner', [('is_company', '=', True)], limit=10)

# Leer registros
partners = odoo.read('res.partner', domain=[('is_company', '=', True)], 
                    fields=['name', 'email', 'phone'])

# Crear registro
new_partner_id = odoo.create('res.partner', {
    'name': 'Nuevo Cliente',
    'email': 'cliente@ejemplo.com',
    'is_company': True
})

# Actualizar registros
odoo.update('res.partner', [new_partner_id], {'phone': '+1234567890'})

# Eliminar registros
odoo.delete('res.partner', [new_partner_id])
```

### Operaciones avanzadas

```python
import pandas as pd

# Crear registros desde DataFrame
df = pd.DataFrame({
    'name': ['Cliente 1', 'Cliente 2', 'Cliente 3'],
    'email': ['c1@ejemplo.com', 'c2@ejemplo.com', 'c3@ejemplo.com']
})

field_map = {
    'name': 'name',
    'email': 'email'
}

result = odoo.create_from_df('res.partner', df, field_map, 
                            static_values={'is_company': True})
print(f"Creados {result['total_created']} registros")

# Upsert (crear o actualizar)
partner_id, was_created = odoo.upsert_by_external_id(
    'res.partner', 'ref', 'CLI001',
    {'name': 'Cliente Actualizado', 'email': 'nuevo@ejemplo.com'}
)
```

### Soporte multi-compañía

```python
# Trabajar con una compañía específica
company_id = 1

# Buscar solo en esa compañía
partners = odoo.read('res.partner', company_id=company_id)

# Crear registro en esa compañía
new_id = odoo.create('res.partner', {'name': 'Partner'}, company_id=company_id)
```

### 🔗 Exploración de Relaciones *(Nuevo en v0.2.0)*

Una de las características más potentes de `managerodooapi` es su capacidad para explorar y navegar por las relaciones entre modelos de Odoo de manera intuitiva.

```python
# Obtener todas las relaciones de un modelo
relations = odoo.get_model_relations('res.partner')
print("Relaciones encontradas:")
for field, info in relations.items():
    print(f"• {field}: {info['type']} → {info['relation']}")

# Explorar estructura completa con relaciones anidadas
structure = odoo.explore_model_structure('sale.order', max_depth=2)
print(f"Modelo: {structure['model']}")
print(f"Campos relacionales: {structure['field_count']}")

# Encontrar qué modelos referencian a otro modelo
reverse_relations = odoo.get_reverse_relations('res.partner')
print("Modelos que referencian a res.partner:")
for model, fields in reverse_relations.items():
    print(f"• {model}: {', '.join(fields)}")

# Obtener registros relacionados eficientemente
customer_id = 123
orders = odoo.get_related_records(
    'res.partner', customer_id, 'sale_order_ids',
    fields=['name', 'date_order', 'amount_total'],
    limit=10
)

# Analizar uso de campos relacionales
analysis = odoo.analyze_model_usage('res.partner', sample_size=100)
print(f"Uso promedio de relaciones: {analysis['usage_stats']['avg_relations_used']:.1f}%")
```

### Operaciones específicas de Odoo

```python
# Confirmar órdenes de venta
order_ids = [1, 2, 3]
odoo.confirm_sale_order(order_ids)

# Ejecutar cualquier método de Odoo
result = odoo.execute_kw(
    odoo.creds.db, odoo.uid, odoo.creds.password,
    'sale.order', 'action_confirm', [order_ids]
)
```

## 📚 Ejemplos Completos

### Gestión de Productos

```python
from managerodooapi import OdooConnector, Credentials

# Conectar
creds = Credentials("http://localhost:8069", "mi_db", "admin", "admin")
odoo = OdooConnector(creds)

# Crear categoría de producto
category_id = odoo.create('product.category', {'name': 'Electrónicos'})

# Crear productos
products_data = [
    {
        'name': 'Laptop Gaming',
        'list_price': 1299.99,
        'categ_id': category_id,
        'type': 'product'
    },
    {
        'name': 'Mouse Inalámbrico', 
        'list_price': 29.99,
        'categ_id': category_id,
        'type': 'product'
    }
]

created_ids = odoo.create('product.product', products_data)
print(f"Productos creados: {created_ids}")

# Actualizar precios con descuento del 10%
for product_id in created_ids:
    product_data = odoo.read('product.product', 
                           domain=[('id', '=', product_id)], 
                           fields=['list_price'])[0]
    new_price = product_data['list_price'] * 0.9
    odoo.update('product.product', [product_id], {'list_price': new_price})
```

### Importación masiva desde Excel

```python
import pandas as pd

# Leer archivo Excel
df = pd.read_excel('clientes.xlsx')

# Mapear columnas
field_map = {
    'Nombre': 'name',
    'Email': 'email', 
    'Teléfono': 'phone',
    'Ciudad': 'city'
}

# Valores estáticos para todos los registros
static_values = {
    'is_company': True,
    'customer_rank': 1
}

# Importar en lotes
result = odoo.create_from_df('res.partner', df, field_map, 
                            static_values=static_values, batch_size=100)

print(f"Procesados: {result['total_processed']}")
print(f"Creados: {result['total_created']}")
print(f"Errores: {len(result['errors'])}")

# Mostrar errores si los hay
for error in result['errors']:
    print(f"Error: {error}")
```

## 🛠️ API Reference

### OdooConnector

La clase principal para todas las operaciones con Odoo.

#### Métodos principales:

- `search(model, domain, limit, company_id)`: Buscar IDs de registros
- `read(model, fields, domain, limit, company_id)`: Leer datos de registros  
- `create(model, values, company_id)`: Crear uno o múltiples registros
- `update(model, ids, values, company_id)`: Actualizar registros existentes
- `delete(model, ids, company_id)`: Eliminar registros
- `create_from_df(model, df, field_map, ...)`: Crear registros desde DataFrame
- `upsert_by_external_id(...)`: Crear o actualizar por ID externo
- `execute_kw(...)`: Ejecutar cualquier método de Odoo

### Credentials

Clase para almacenar credenciales de conexión.

```python
@dataclass
class Credentials:
    url: str      # URL del servidor Odoo
    db: str       # Nombre de la base de datos
    username: str # Usuario
    password: str # Contraseña
```

## 🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. Push a la rama (`git push origin feature/AmazingFeature`)
5. Abre un Pull Request

## 📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo `LICENSE` para más detalles.

## 🐛 Reportar Issues

Si encuentras algún bug o tienes una sugerencia, por favor crea un issue en GitHub.

## 📞 Soporte

Para soporte técnico o preguntas, puedes:
- Crear un issue en GitHub
- Revisar la documentación
- Consultar los ejemplos incluidos

---

**Desarrollado con ❤️ para la comunidad Odoo**