Skip to content

unclecatvn/agent-skills / skills/odoo-19.0

odoo-19

Verified

Odoo 19 development knowledge base with 18 specialized guides covering Actions (ir.actions.*, cron jobs, server actions), Controllers (HTTP routing, endpoints, auth types), Data files (XML/CSV records, shortcuts, noupdate), API Decorators (@api.depends, @api.constrains, @api.ondelete, @api.onchange, @api.model, @api.private), SQL Constraints (models.Constraint replacing _sql_constraints), Database Indexes (models.Index), Module development (manifest, wizards, reports), Field types (Char, Text, Monetary, relational fields), Manifest configuration (__manifest__.py, dependencies, asset bundles), Mixins (mail.thread, mail.activity.mixin, mail.alias.mixin, utm.mixin), ORM Model methods (search, CRUD, domain filters, recordsets, CamelCase model naming), Migration scripts (pre/post/end hooks, data migration), OWL frontend components (hooks, services, lifecycle), Performance optimization (N+1 prevention, batch ops, _read_group), QWeb Reports (PDF/HTML, paper formats, barcodes, t-out), Security/ACL (record rules, field permissions, privilege-based groups, @api.private), Testing (TransactionCase, HttpCase, mocking, query count assertions), Transactions (savepoints, UniqueViolation, serialization failures), Translations (i18n, PO files, translatable fields), XML Views (list/form/search, kanban card templates, xpath inheritance, QWeb templates). Use when writing, reviewing, or debugging any Odoo 19 Python or XML code, creating or modifying modules, fixing performance issues, or looking up Odoo 19 API patterns and best practices. Includes CSS/SCSS asset authoring and review for Odoo addons.

references/odoo-19-decorator-guide.md

View on GitHub
# Odoo 19 Decorator Guide

## Coding Conventions

- Keep field declarations and their default, compute, inverse, search, and
  constraint helpers together; name helpers after the field and operation.
- Use `@api.model_create_multi` for `create()` overrides, declare complete
  dotted dependencies for computed fields, and keep constraints batch-safe.
- Use `@api.ondelete(at_uninstall=False)` for deletion validation; do not use
  onchange methods to perform persistence or business-side effects.

Guide for using `@api` decorators in Odoo 19: computed fields, validation, onchange, and more.

## Table of Contents

- [Method Decorators](#method-decorators)
- [@api.depends](#apidepends)
- [@api.constrains](#apiconstrains)
- [@api.ondelete](#apiondelete)
- [@api.onchange](#apionchange)
- [@api.model](#apimodel)
- [@api.model_create_multi](#apimodel_create_multi)
- [@api.autovacuum](#apiautovacuum)
- [@api.private](#apiprivate)
- [@api.returns](#apireturns)

---

## Method Decorators

Decorators in Odoo 19 are in `odoo.api` module:

```python
from odoo import api, models

class MyModel(models.Model):
    _name = 'my.model'

    @api.depends('field')
    def _compute_method(self):
        pass
```

---

## @api.depends

For computed fields. Specifies dependencies that trigger recomputation.

### Basic Usage

```python
total = fields.Float(compute='_compute_total', store=True)

@api.depends('value', 'tax')
def _compute_total(self):
    for record in self:
        record.total = record.value + record.value * record.tax
```

### Dotted Paths

Can use dotted paths for relational fields:

```python
@api.depends('partner_id.email')
def _compute_email(self):
    for record in self:
        record.email = record.partner_id.email
```

### Multiple Fields

Compute multiple fields:

```python
discount_value = fields.Float(compute='_apply_discount')
total = fields.Float(compute='_apply_discount')

@api.depends('value', 'discount')
def _apply_discount(self):
    for record in self:
        discount = record.value * record.discount
        record.discount_value = discount
        record.total = record.value - discount
```

### Search on Computed Field

```python
upper_name = fields.Char(compute='_compute_upper', search='_search_upper')

@api.depends('name')
def _compute_upper(self):
    for record in self:
        record.upper_name = record.name.upper() if record.name else False

def _search_upper(self, operator, value):
    if operator == 'like':
        operator = 'ilike'
    return [('name', operator, value)]
```

### Inverse Method

Allow setting computed field:

```python
document = fields.Char(compute='_get_document', inverse='_set_document')

@api.depends('document_path')
def _get_document(self):
    for record in self:
        with open(record.document_path) as f:
            record.document = f.read()

def _set_document(self):
    for record in self:
        if not record.document:
            continue
        with open(record.document_path, "w", encoding="utf-8") as f:
            f.write(record.document)
```

---

## @api.constrains

For validation. Called on create and write.

### Basic Usage

```python
@api.constrains('email')
def _check_email(self):
    for record in self:
        if not tools.email_validation(record.email):
            raise ValidationError("Invalid email")
```

### Multiple Fields

```python
@api.constrains('date_start', 'date_end')
def _check_dates(self):
    for record in self:
        if record.date_end < record.date_start:
            raise ValidationError("End date must be after start date")
```

### No Dotted Paths

Unlike `@api.depends`, **cannot use dotted paths**:

```python
# BAD: dotted path not supported
@api.constrains('partner_id.email')
def _check_email(self):
    pass

# GOOD: use simple field name
@api.constrains('partner_id')
def _check_email(self):
    for record in self:
        if not tools.email_validation(record.partner_id.email):
            raise ValidationError("Invalid email")
```

---

## @api.ondelete

For delete validation (Odoo 18+).

```python
@api.ondelete(at_uninstall=False)
def _unlink_if_not_draft(self):
    if any(rec.state != 'draft' for rec in self):
        raise UserError("Cannot delete non-draft records")
```

### Parameters

| Parameter      | Description                                            |
| -------------- | ------------------------------------------------------ |
| `at_uninstall` | If `False`, allows deletion when module is uninstalled |

### Why Use @api.ondelete?

- **Better than overriding `unlink()`**: Doesn't break module uninstall
- **Clear intent**: Explicitly for delete validation
- **Automatic**: Called before deletion

### Unlink Override (Anti-pattern)

```python
# BAD: breaks module uninstall
def unlink(self):
    if any(rec.state != 'draft' for rec in self):
        raise UserError("Cannot delete non-draft records")
    return super().unlink()
```

---

## @api.onchange

For form UI updates when field values change.

### Basic Usage

```python
@api.onchange('partner_id')
def _onchange_partner_id(self):
    if self.partner_id:
        self.email = self.partner_id.email
        self.phone = self.partner_id.phone
```

### Multiple Fields

```python
@api.onchange('country_id', 'state_id')
def _onchange_location(self):
    if self.country_id:
            # Update zip format
            pass
```

### No CRUD Operations

**Important**: `onchange` methods should **not** perform CRUD operations.

```python
# BAD: create in onchange
@api.onchange('field1')
def _onchange_field1(self):
    self.env['another.model'].create({'name': 'test'})

# GOOD: only modify current record
@api.onchange('field1')
def _onchange_field1(self):
    self.field2 = 'computed value'
```

### Return Warning

```python
@api.onchange('amount')
def _onchange_amount(self):
    if self.amount < 0:
        return {
            'warning': {
                'title': "Warning",
                'message': "Amount cannot be negative",
            }
        }
```

---

## @api.model

For model-level methods that don't depend on `self`.

### Usage

```python
@api.model
def get_default_values(self):
    return {
        'field1': 'value1',
        'field2': 'value2',
    }
```

### Can be called on any recordset

```python
# Can call on any recordset (self may be empty)
record = self.env['my.model'].browse([1, 2, 3])
defaults = record.get_default_values()
```

---

## @api.model_create_multi

For handling batch create operations.

```python
@api.model_create_multi
def create(self, vals_list):
    # Add default values
    for vals in vals_list:
        vals.setdefault('field', 'default')
    return super().create(vals_list)
```

### Why Use It?

Odoo 17+ creates records in batches by default. This decorator ensures proper handling.

---

## @api.autovacuum

For methods to run by cron vacuuem.

```python
@api.autovacuum
def _gc_entries(self):
    # Clean old records
    domain = [('create_date', '<', date.today() - timedelta(days=90)])
    self.search(domain).unlink()
```

---

## Decorator Decision Tree

```
Need to define field behavior?
├── Field computed from other fields → @api.depends
│   └── CAN use dotted paths
├── Validate data → @api.constrains
│   └── CANNOT use dotted paths
├── Prevent record deletion → @api.ondelete
└── Update form UI → @api.onchange
    └── NO CRUD operations allowed

Need to define method behavior?
├── Method-level, doesn't depend on self → @api.model
├── Mark method as non-RPC callable → @api.private
└── Normal record method → no decorator needed
```

---

## @api.private

Marks a method as **not callable via RPC** (external API). Also available in Odoo 18.

### Usage

```python
from odoo import api, models

class MyModel(models.Model):
    _name = 'my.model'

    @api.private
    def compute_totals(self):
        """Public name, but cannot be called via XML-RPC/JSON-RPC."""
        return self._do_heavy_work()

    def public_action(self):
        """This method CAN be called via RPC."""
        return self.compute_totals()
```

### When to Use

- Methods that should only be called internally (not via API/button)
- Public (non-`_`) method names that must not be exposed, e.g. kept for backward compatibility
- ORM override methods that you don't want exposed

### @api.private vs Underscore Convention

```python
# Underscore prefix: refused over RPC by odoo/service/model.py (get_public_method)
def _do_stuff(self):
    pass

# @api.private: same RPC refusal for a method whose name has no underscore
@api.private
def compute_sensitive_data(self):  # Name doesn't need underscore
    pass
```

---

---

## @api.returns

**Removed in Odoo 19.** `odoo.api` no longer exports `returns` (it existed up to 18), so
`@api.returns(...)` fails when the module is imported. Drop the decorator and return the
recordset directly; overrides such as `copy()` or `message_post()` need no decorator.

---

## Common Patterns

### Computed Field with Inverse

```python
total = fields.Float(compute='_compute_total', inverse='_inverse_total', store=True)

@api.depends('subtotal', 'tax')
def _compute_total(self):
    for record in self:
        record.total = record.subtotal + record.tax

def _inverse_total(self):
    for record in self:
        record.subtotal = record.total - record.tax
```

### Validation with Constraints

```python
@api.constrains('age')
def _check_age(self):
    for record in self:
        if record.age < 18:
            raise ValidationError("Must be 18 or older")
```

### Delete Validation

```python
@api.ondelete(at_uninstall=False)
def _unlink_if_not_cancelled(self):
    if any(rec.state != 'cancel' for rec in self):
        raise UserError("Only cancelled records can be deleted")
```

### Onchange for Defaults

```python
@api.onchange('partner_id')
def _onchange_partner_id(self):
    if self.partner_id:
        self.lang = self.partner_id.lang
        self.user_id = self.partner_id.user_id
```

---

## References

- Source: Odoo 19 documentation `/doc/developer/reference/backend/orm.rst`
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall