Toggle navigation

ORM API

Object Relational Mapping module:
  • Hierarchical structure
  • Constraints consistency and validation
  • Object metadata depends on its status
  • Optimised processing by complex query (multiple actions at once)
  • Default field values
  • Permissions optimisation
  • Persistent object: DB postgresql
  • Data conversion
  • Multi-level caching system
  • Two different inheritance mechanisms
  • Rich set of field types:
    • classical (varchar, integer, boolean, …)
    • relational (one2many, many2one, many2many)
    • functional

Models

Model fields are defined as attributes on the model itself:

from odoo import models, fields
class AModel(models.Model):
    _name = 'a.model.name'

    field1 = fields.Char()

By default, the field’s label (user-visible name) is a capitalized version of the field name, this can be overridden with the string parameter.

field2 = fields.Integer(string="Field Label")

For the list of field types and parameters, see the fields reference.

Default values are defined as parameters on fields, either as a value:

name = fields.Char(default="a value")

or as a function called to compute the default value, which should return that value:

def _default_name(self):
    return self.get_value()

name = fields.Char(default=lambda self: self._default_name())

API

class odoo.models.BaseModel[source]

Base class for Odoo models.

Odoo models are created by inheriting one of the following:

  • Model for regular database-persisted models
  • TransientModel for temporary data, stored in the database but automatically vacuumed every so often
  • AbstractModel for abstract super classes meant to be shared by multiple inheriting models

The system automatically instantiates every model once per database. Those instances represent the available models on each database, and depend on which modules are installed on that database. The actual class of each instance is built from the Python classes that create and inherit from the corresponding model.

Every model instance is a “recordset”, i.e., an ordered collection of records of the model. Recordsets are returned by methods like browse(), search(), or field accesses. Records have no explicit representation: a record is represented as a recordset of one record.

To create a class that should not be instantiated, the _register attribute may be set to False.

_auto = False

Whether a database table should be created. If set to False, override init() to create the database table.

Automatically defaults to True for Model and TransientModel, False for AbstractModel.

_log_access

Whether the ORM should automatically generate and update the Access Log fields.

Defaults to whatever value was set for _auto.

_table = None

SQL table name used by model if _auto

_sequence = None

SQL sequence to use for ID field

_sql_constraints = []

SQL constraints [(name, sql_def, message)]

_register = True

registry visibility

_abstract = True

Whether the model is abstract.

_transient = False

Whether the model is transient.

_name = None

the model name (in dot-notation, module namespace)

_description = None

the model’s informal name

_inherit = None

Python-inherited models:

Type
_inherits = {}

dictionary {‘parent_model’: ‘m2o_field’} mapping the _name of the parent business objects to the names of the corresponding foreign key fields to use:

_inherits = {
    'a.model': 'a_field_id',
    'b.model': 'b_field_id'
}

implements composition-based inheritance: the new model exposes all the fields of the inherited models but stores none of them: the values themselves remain stored on the linked record.

_rec_name = None

field to use for labeling records, default: name

_order = 'id'

default order field for searching results

_check_company_auto = False

On write and create, call _check_company to ensure companies consistency on the relational fields having check_company=True as attribute.

_parent_name = 'parent_id'

the many2one field used as parent field

_parent_store = False

set to True to compute parent_path field.

Alongside a parent_path field, sets up an indexed storage of the tree structure of records, to enable faster hierarchical queries on the records of the current model using the child_of and parent_of domain operators.

_date_name = 'date'

field to use for default calendar view

_fold_name = 'fold'

field to determine folded groups in kanban views

AbstractModel

odoo.models.AbstractModel[source]

alias of odoo.models.BaseModel

Model

class odoo.models.Model[source]

Main super-class for regular database-persisted Odoo models.

Odoo models are created by inheriting from this class:

class user(Model):
    ...

The system will later instantiate the class once per database (on which the class’ module is installed).

_auto = True
_abstract = False
_transient = False

TransientModel

class odoo.models.TransientModel[source]

Model super-class for transient records, meant to be temporarily persistent, and regularly vacuum-cleaned.

A TransientModel has a simplified access rights management, all users can create new records, and may only access the records they created. The superuser has unrestricted access to all TransientModel records.

_auto = True
_abstract = False
_transient = True

Fields

class odoo.fields.Field[source]

The field descriptor contains the field definition, and manages accesses and assignments of the corresponding field on records. The following attributes may be provided when instanciating a field:

Parameters
  • string (str) – the label of the field seen by users; if not set, the ORM takes the field name in the class (capitalized).
  • help (str) – the tooltip of the field seen by users
  • invisible – whether the field is invisible (boolean, by default False)
  • readonly (bool) –

    whether the field is readonly (default: False)

    This only has an impact on the UI. Any field assignation in code will work (if the field is a stored field or an inversable one).

  • required (bool) – whether the value of the field is required (default: False)
  • index (bool) – whether the field is indexed in database. Note: no effect on non-stored and virtual fields. (default: False)
  • default (value or callable) – the default value for the field; this is either a static value, or a function taking a recordset and returning a value; use default=None to discard default values for the field
  • states (dict) –

    a dictionary mapping state values to lists of UI attribute-value pairs; possible attributes are: readonly, required, invisible.

  • groups (str) – comma-separated list of group xml ids (string); this restricts the field access to the users of the given groups only
  • company_dependent (bool) –

    whether the field value is dependent of the current company;

    The value isn’t stored on the model table. It is registered as ir.property. When the value of the company_dependent field is needed, an ir.property is searched, linked to the current company (and current record if one property exists).

    If the value is changed on the record, it either modifies the existing property for the current record (if one exists), or creates a new one for the current company and res_id.

    If the value is changed on the company side, it will impact all records on which the value hasn’t been changed.

  • copy (bool) – whether the field value should be copied when the record is duplicated (default: True for normal fields, False for one2many and computed fields, including property fields and related fields)
  • store (bool) – whether the field is stored in database (default:True, False for computed fields)
  • group_operator (str) –

    aggregate function used by read_group() when grouping on this field.

    Supported aggregate functions are:

    • array_agg : values, including nulls, concatenated into an array
    • count : number of rows
    • count_distinct : number of distinct rows
    • bool_and : true if all values are true, otherwise false
    • bool_or : true if at least one value is true, otherwise false
    • max : maximum value of all values
    • min : minimum value of all values
    • avg : the average (arithmetic mean) of all values
    • sum : sum of all values
  • group_expand (str) –

    function used to expand read_group results when grouping on the current field.

    @api.model
    def _read_group_selection_field(self, values, domain, order):
        return ['choice1', 'choice2', ...] # available selection choices.
    
    @api.model
    def _read_group_many2one_field(self, records, domain, order):
        return records + self.search([custom_domain])
    

Computed Fields

Parameters
  • compute (str) –

    name of a method that computes the field

  • compute_sudo (bool) – whether the field should be recomputed as superuser to bypass access rights (by default True for stored fields, False for non stored fields)
  • inverse (str) – name of a method that inverses the field (optional)
  • search (str) – name of a method that implement search on the field (optional)
  • related (str) –

    sequence of field names

Basic Fields

class odoo.fields.Boolean[source]

Encapsulates a bool.

class odoo.fields.Char[source]

Basic string field, can be length-limited, usually displayed as a single-line string in clients.

Parameters
  • size (int) – the maximum size of values stored for that field
  • trim (bool) – states whether the value is trimmed or not (by default, True). Note that the trim operation is applied only by the web client.
  • translate (bool or callable) – enable the translation of the field’s values; use translate=True to translate field values as a whole; translate may also be a callable such that translate(callback, value) translates value by using callback(term) to retrieve the translation of terms.
class odoo.fields.Float[source]

Encapsulates a float.

The precision digits are given by the (optional) digits attribute.

Parameters
digits (tuple(int,int) or str) – a pair (total, decimal) or a string referencing a DecimalPrecision record name.

When a float is a quantity associated with an unit of measure, it is important to use the right tool to compare or round values with the correct precision.

The Float class provides some static methods for this purpose:

round() to round a float with the given precision. is_zero() to check if a float equals zero at the given precision. compare() to compare two floats at the given precision.

class odoo.fields.Integer[source]

Encapsulates an int.

Advanced Fields

class odoo.fields.Binary[source]

Encapsulates a binary content (e.g. a file).

Parameters
attachment (bool) – whether the field should be stored as ir_attachment or in a column of the model’s table (default: True).
class odoo.fields.Html[source]

Encapsulates an html code content.

Parameters
  • sanitize (bool) – whether value must be sanitized (default: True)
  • sanitize_tags (bool) – whether to sanitize tags (only a white list of attributes is accepted, default: True)
  • sanitize_attributes (bool) – whether to sanitize attributes (only a white list of attributes is accepted, default: True)
  • sanitize_style (bool) – whether to sanitize style attributes (default: False)
  • strip_style (bool) – whether to strip style attributes (removed and therefore not sanitized, default: False)
  • strip_classes (bool) – whether to strip classes attributes (default: False)
class odoo.fields.Image[source]

Encapsulates an image, extending Binary.

If image size is greater than the max_width/max_height limit of pixels, the image will be resized to the limit by keeping aspect ratio.

Parameters
  • max_width (int) – the maximum width of the image (default: 0, no limit)
  • max_height (int) – the maximum height of the image (default: 0, no limit)
  • verify_resolution (bool) – whether the image resolution should be verified to ensure it doesn’t go over the maximum image resolution (default: True). See odoo.tools.image.ImageProcess for maximum image resolution (default: 45e6).
class odoo.fields.Monetary[source]

Encapsulates a float expressed in a given res_currency.

The decimal precision and currency symbol are taken from the currency_field attribute.

Parameters
currency_field (str) – name of the Many2one field holding the res_currency this monetary field is expressed in (default: 'currency_id')
class odoo.fields.Selection[source]

Encapsulates an exclusive choice between different values.

Parameters
  • selection (list(tuple(str,str)) or callable or str) – specifies the possible values for this field. It is given as either a list of pairs (value, label), or a model method, or a method name.
  • selection_add (list(tuple(str,str))) –

    provides an extension of the selection in the case of an overridden field. It is a list of pairs (value, label) or singletons (value,), where singleton values must appear in the overridden selection. The new values are inserted in an order that is consistent with the overridden selection and this list:

    selection = [('a', 'A'), ('b', 'B')]
    selection_add = [('c', 'C'), ('b',)]
    > result = [('a', 'A'), ('c', 'C'), ('b', 'B')]
    
  • ondelete

    provides a fallback mechanism for any overridden field with a selection_add. It is a dict that maps every option from the selection_add to a fallback action.

    This fallback action will be applied to all records whose selection_add option maps to it.

    The actions can be any of the following:
    • ’set null’ – the default, all records with this option will have their selection value set to False.
    • ’cascade’ – all records with this option will be deleted along with the option itself.
    • ’set default’ – all records with this option will be set to the default of the field definition
    • <callable> – a callable whose first and only argument will be the set of records containing the specified Selection option, for custom processing

The attribute selection is mandatory except in the case of related or extended fields.

class odoo.fields.Text[source]

Very similar to Char but used for longer contents, does not have a size and usually displayed as a multiline text box.

Parameters
translate (bool or callable) – enable the translation of the field’s values; use translate=True to translate field values as a whole; translate may also be a callable such that translate(callback, value) translates value by using callback(term) to retrieve the translation of terms.

Date(time) Fields

Dates and Datetimes are very important fields in any kind of business application. Their misuse can create invisible yet painful bugs, this section aims to provide Odoo developers with the knowledge required to avoid misusing these fields.

When assigning a value to a Date/Datetime field, the following options are valid:

  • A date or datetime object.
  • A string in the proper server format:

    • YYYY-MM-DD for Date fields,
    • YYYY-MM-DD HH:MM:SS for Datetime fields.
  • False or None.

The Date and Datetime fields class have helper methods to attempt conversion into a compatible type:

Date / Datetime comparison best practices:

  • Date fields can only be compared to date objects.
  • Datetime fields can only be compared to datetime objects.

Common operations with dates and datetimes such as addition, substraction or fetching the start/end of a period are exposed through both Date and Datetime. These helpers are also available by importing odoo.tools.date_utils.

class odoo.fields.Date[source]

Encapsulates a python date object.

static add(value, *args, **kwargs)[source]

Return the sum of value and a relativedelta.

Parameters
  • value – initial date or datetime.
  • args – positional args to pass directly to relativedelta.
  • kwargs – keyword args to pass directly to relativedelta.
Returns
the resulting date/datetime.
static context_today(record, timestamp=None)[source]

Return the current date as seen in the client’s timezone in a format fit for date fields.

Parameters
  • record – recordset from which the timezone will be obtained.
  • timestamp (datetime) – optional datetime value to use instead of the current date and time (must be a datetime, regular dates can’t be converted between timezones).
Return type
date
static end_of(value, granularity)[source]

Get end of a time period from a date or a datetime.

Parameters
  • value – initial date or datetime.
  • granularity – Type of period in string, can be year, quarter, month, week, day or hour.
Returns
A date/datetime object corresponding to the start of the specified period.
static start_of(value, granularity)[source]

Get start of a time period from a date or a datetime.

Parameters
  • value – initial date or datetime.
  • granularity – type of period in string, can be year, quarter, month, week, day or hour.
Returns
a date/datetime object corresponding to the start of the specified period.
static subtract(value, *args, **kwargs)[source]

Return the difference between value and a relativedelta.

Parameters
  • value – initial date or datetime.
  • args – positional args to pass directly to relativedelta.
  • kwargs – keyword args to pass directly to relativedelta.
Returns
the resulting date/datetime.
static to_date(value)[source]

Attempt to convert value to a date object.

Parameters
value (str or date or datetime) – value to convert.
Returns
an object representing value.
Return type
date or None
static to_string(value)[source]

Convert a date or datetime object to a string.

Parameters
value – value to convert.
Returns
a string representing value in the server’s date format, if value is of type datetime, the hours, minute, seconds, tzinfo will be truncated.
Return type
static today(*args)[source]

Return the current day in the format expected by the ORM.

class odoo.fields.Datetime[source]

Encapsulates a python datetime object.

static add(value, *args, **kwargs)[source]

Return the sum of value and a relativedelta.

Parameters
  • value – initial date or datetime.
  • args – positional args to pass directly to relativedelta.
  • kwargs – keyword args to pass directly to relativedelta.
Returns
the resulting date/datetime.
static context_timestamp(record, timestamp)[source]

Return the given timestamp converted to the client’s timezone.

Parameters
  • record – recordset from which the timezone will be obtained.
  • timestamp (datetime) – naive datetime value (expressed in UTC) to be converted to the client timezone.
Returns
timestamp converted to timezone-aware datetime in context timezone.
Return type
datetime
static end_of(value, granularity)[source]

Get end of a time period from a date or a datetime.

Parameters
  • value – initial date or datetime.
  • granularity – Type of period in string, can be year, quarter, month, week, day or hour.
Returns
A date/datetime object corresponding to the start of the specified period.
static now(*args)[source]

Return the current day and time in the format expected by the ORM.

static start_of(value, granularity)[source]

Get start of a time period from a date or a datetime.

Parameters
  • value – initial date or datetime.
  • granularity – type of period in string, can be year, quarter, month, week, day or hour.
Returns
a date/datetime object corresponding to the start of the specified period.
static subtract(value, *args, **kwargs)[source]

Return the difference between value and a relativedelta.

Parameters
  • value – initial date or datetime.
  • args – positional args to pass directly to relativedelta.
  • kwargs – keyword args to pass directly to relativedelta.
Returns
the resulting date/datetime.
static to_datetime(value)[source]

Convert an ORM value into a datetime value.

Parameters
value (str or date or datetime) – value to convert.
Returns
an object representing value.
Return type
datetime or None
static to_string(value)[source]

Convert a datetime or date object to a string.

Parameters
value (datetime or date) – value to convert.
Returns
a string representing value in the server’s datetime format, if value is of type date, the time portion will be midnight (00:00:00).
Return type
static today(*args)[source]

Return the current day, at midnight (00:00:00).

Relational Fields

class odoo.fields.Many2one[source]

The value of such a field is a recordset of size 0 (no record) or 1 (a single record).

Parameters
  • comodel_name (str) – name of the target model Mandatory except for related or extended fields.
  • domain – an optional domain to set on candidate values on the client side (domain or string)
  • context (dict) – an optional context to use on the client side when handling that field
  • ondelete (str) – what to do when the referred record is deleted; possible values are: 'set null', 'restrict', 'cascade'
  • auto_join (bool) – whether JOINs are generated upon search through that field (default: False)
  • delegate (bool) – set it to True to make fields of the target model accessible from the current model (corresponds to _inherits)
  • check_company (bool) – Mark the field to be verified in _check_company(). Add a default company domain depending on the field attributes.
class odoo.fields.One2many[source]

One2many field; the value of such a field is the recordset of all the records in comodel_name such that the field inverse_name is equal to the current record.

Parameters
  • comodel_name (str) – name of the target model
  • inverse_name (str) – name of the inverse Many2one field in comodel_name
  • domain – an optional domain to set on candidate values on the client side (domain or string)
  • context (dict) – an optional context to use on the client side when handling that field
  • auto_join (bool) – whether JOINs are generated upon search through that field (default: False)
  • limit (int) – optional limit to use upon read

The attributes comodel_name and inverse_name are mandatory except in the case of related fields or field extensions.

class odoo.fields.Many2many[source]

Many2many field; the value of such a field is the recordset.

Parameters
  • comodel_name – name of the target model (string) mandatory except in the case of related or extended fields
  • relation (str) – optional name of the table that stores the relation in the database
  • column1 (str) – optional name of the column referring to “these” records in the table relation
  • column2 (str) – optional name of the column referring to “those” records in the table relation

The attributes relation, column1 and column2 are optional. If not given, names are automatically generated from model names, provided model_name and comodel_name are different!

Note that having several fields with implicit relation parameters on a given model with the same comodel is not accepted by the ORM, since those field would use the same table. The ORM prevents two many2many fields to use the same relation parameters, except if

  • both fields use the same model, comodel, and relation parameters are explicit; or
  • at least one field belongs to a model with _auto = False.
Parameters
  • domain – an optional domain to set on candidate values on the client side (domain or string)
  • context (dict) – an optional context to use on the client side when handling that field
  • check_company (bool) – Mark the field to be verified in _check_company(). Add a default company domain depending on the field attributes.
  • limit (int) – optional limit to use upon read

Pseudo-relational fields

class odoo.fields.Reference[source]

Pseudo-relational field (no FK in database).

The field value is stored as a string following the pattern "res_model.res_id" in database.

class odoo.fields.Many2oneReference[source]

Pseudo-relational field (no FK in database).

The field value is stored as an integer id in database.

Contrary to Reference fields, the model has to be specified in a Char field, whose name has to be specified in the model_field attribute for the current Many2oneReference field.

Parameters
model_field (str) – name of the Char where the model name is stored.

Computed Fields

Fields can be computed (instead of read straight from the database) using the compute parameter. It must assign the computed value to the field. If it uses the values of other fields, it should specify those fields using depends().

from odoo import api
total = fields.Float(compute='_compute_total')

@api.depends('value', 'tax')
def _compute_total(self):
    for record in self:
        record.total = record.value + record.value * record.tax
  • dependencies can be dotted paths when using sub-fields:

    @api.depends('line_ids.value')
    def _compute_total(self):
        for record in self:
            record.total = sum(line.value for line in record.line_ids)
    
  • computed fields are not stored by default, they are computed and returned when requested. Setting store=True will store them in the database and automatically enable searching.
  • searching on a computed field can also be enabled by setting the search parameter. The value is a method name returning a Search domains.

    upper_name = field.Char(compute='_compute_upper', search='_search_upper')
    
    def _search_upper(self, operator, value):
        if operator == 'like':
            operator = 'ilike'
        return [('name', operator, value)]
    

    The search method is invoked when processing domains before doing an actual search on the model. It must return a domain equivalent to the condition: field operator value.

  • Computed fields are readonly by default. To allow setting values on a computed field, use the inverse parameter. It is the name of a function reversing the computation and setting the relevant fields:

    document = fields.Char(compute='_get_document', inverse='_set_document')
    
    def _get_document(self):
        for record in self:
            with open(record.get_document_path) as f:
                record.document = f.read()
    def _set_document(self):
        for record in self:
            if not record.document: continue
            with open(record.get_document_path()) as f:
                f.write(record.document)
    
  • multiple fields can be computed at the same time by the same method, just use the same method on all fields and set all of them:

    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:
            # compute actual discount from discount percentage
            discount = record.value * record.discount
            record.discount_value = discount
            record.total = record.value - discount
    

Automatic fields

odoo.fields.id

Identifier field

If length of current recordset is 1, return id of unique record in it.

Raise an Error otherwise.

Access Log fields

These fields are automatically set and updated if _log_access is enabled. It can be disabled to avoid creating or updating those fields on tables for which they are not useful.

By default, _log_access is set to the same value as _auto

odoo.fields.create_date

Stores when the record was created, Datetime

odoo.fields.create_uid

Stores who created the record, Many2one to a res.users.

odoo.fields.write_date

Stores when the record was last updated, Datetime

odoo.fields.write_uid

Stores who last updated the record, Many2one to a res.users.

Reserved Field names

A few field names are reserved for pre-defined behaviors beyond that of automated fields. They should be defined on a model when the related behavior is desired:

odoo.fields.name

default value for _rec_name, used to display records in context where a representative “naming” is necessary.

Char

odoo.fields.active

toggles the global visibility of the record, if active is set to False the record is invisible in most searches and listing.

Boolean

odoo.fields.state

lifecycle stages of the object, used by the states attribute on fields.

Selection

odoo.fields.parent_id

default_value of _parent_name, used to organize records in a tree structure and enables the child_of and parent_of operators in domains.

Many2one

odoo.fields.parent_path

When _parent_store is set to True, used to store a value reflecting the tree structure of _parent_name, and to optimize the operators child_of and parent_of in search domains. It must be declared with index=True for proper operation.

Char

odoo.fields.company_id

Main field name used for Odoo multi-company behavior.

Used by :meth:~odoo.models._check_company to check multi company consistency. Defines whether a record is shared between companies (no value) or only accessible by the users of a given company.

Many2one :type: res_company

Recordsets

Interactions with models and records are performed through recordsets, an ordered collection of records of the same model.

Methods defined on a model are executed on a recordset, and their self is a recordset:

class AModel(models.Model):
    _name = 'a.model'
    def a_method(self):
        # self can be anything between 0 records and all records in the
        # database
        self.do_operation()

Iterating on a recordset will yield new sets of a single record (“singletons”), much like iterating on a Python string yields strings of a single characters:

def do_operation(self):
    print(self) # => a.model(1, 2, 3, 4, 5)
    for record in self:
        print(record) # => a.model(1), then a.model(2), then a.model(3), ...

Field access

Recordsets provide an “Active Record” interface: model fields can be read and written directly from the record as attributes.

Field values can also be accessed like dict items, which is more elegant and safer than getattr() for dynamic field names. Setting a field’s value triggers an update to the database:

>>> record.name
Example Name
>>> record.company_id.name
Company Name
>>> record.name = "Bob"
>>> field = "name"
>>> record[field]
Bob

Accessing a relational field (Many2one, One2many, Many2many) always returns a recordset, empty if the field is not set.

Record cache and prefetching

Odoo maintains a cache for the fields of the records, so that not every field access issues a database request, which would be terrible for performance. The following example queries the database only for the first statement:

record.name             # first access reads value from database
record.name             # second access gets value from cache

To avoid reading one field on one record at a time, Odoo prefetches records and fields following some heuristics to get good performance. Once a field must be read on a given record, the ORM actually reads that field on a larger recordset, and stores the returned values in cache for later use. The prefetched recordset is usually the recordset from which the record comes by iteration. Moreover, all simple stored fields (boolean, integer, float, char, text, date, datetime, selection, many2one) are fetched altogether; they correspond to the columns of the model’s table, and are fetched efficiently in the same query.

Consider the following example, where partners is a recordset of 1000 records. Without prefetching, the loop would make 2000 queries to the database. With prefetching, only one query is made:

for partner in partners:
    print partner.name          # first pass prefetches 'name' and 'lang'
                                # (and other fields) on all 'partners'
    print partner.lang

The prefetching also works on secondary records: when relational fields are read, their values (which are records) are subscribed for future prefetching. Accessing one of those secondary records prefetches all secondary records from the same model. This makes the following example generate only two queries, one for partners and one for countries:

countries = set()
for partner in partners:
    country = partner.country_id        # first pass prefetches all partners
    countries.add(country.name)         # first pass prefetches all countries

Method decorators

The Odoo API module defines Odoo Environments and method decorators.

odoo.api.autovacuum(method)[source]

Decorate a method so that it is called by the daily vacuum cron job (model ir.autovacuum). This is typically used for garbage-collection-like tasks that do not deserve a specific cron job.

odoo.api.constrains(*args)[source]

Decorate a constraint checker.

Each argument must be a field name used in the check:

@api.constrains('name', 'description')
def _check_description(self):
    for record in self:
        if record.name == record.description:
            raise ValidationError("Fields name and description must be different")

Invoked on the records on which one of the named fields has been modified.

Should raise ValidationError if the validation failed.

odoo.api.depends(*args)[source]

Return a decorator that specifies the field dependencies of a “compute” method (for new-style function fields). Each argument must be a string that consists in a dot-separated sequence of field names:

pname = fields.Char(compute='_compute_pname')

@api.depends('partner_id.name', 'partner_id.is_company')
def _compute_pname(self):
    for record in self:
        if record.partner_id.is_company:
            record.pname = (record.partner_id.name or "").upper()
        else:
            record.pname = record.partner_id.name

One may also pass a single function as argument. In that case, the dependencies are given by calling the function with the field’s model.

odoo.api.depends_context(*args)[source]

Return a decorator that specifies the context dependencies of a non-stored “compute” method. Each argument is a key in the context’s dictionary:

price = fields.Float(compute='_compute_product_price')

@api.depends_context('pricelist')
def _compute_product_price(self):
    for product in self:
        if product.env.context.get('pricelist'):
            pricelist = self.env['product.pricelist'].browse(product.env.context['pricelist'])
        else:
            pricelist = self.env['product.pricelist'].get_default_pricelist()
        product.price = pricelist.get_products_price(product).get(product.id, 0.0)

All dependencies must be hashable. The following keys have special support:

  • company (value in context or current company id),
  • uid (current user id and superuser flag),
  • active_test (value in env.context or value in field.context).
odoo.api.model(method)[source]

Decorate a record-style method where self is a recordset, but its contents is not relevant, only the model is. Such a method:

@api.model
def method(self, args):
    ...
odoo.api.model_create_multi(method)[source]

Decorate a method that takes a list of dictionaries and creates multiple records. The method may be called with either a single dict or a list of dicts:

record = model.create(vals)
records = model.create([vals, ...])
odoo.api.onchange(*args)[source]

Return a decorator to decorate an onchange method for given fields.

In the form views where the field appears, the method will be called when one of the given fields is modified. The method is invoked on a pseudo-record that contains the values present in the form. Field assignments on that record are automatically sent back to the client.

Each argument must be a field name:

@api.onchange('partner_id')
def _onchange_partner(self):
    self.message = "Dear %s" % (self.partner_id.name or "")
return {
    'warning': {'title': "Warning", 'message': "What is this?", 'type': 'notification'},
}

If the type is set to notification, the warning will be displayed in a notification. Otherwise it will be displayed in a dialog as default.

odoo.api.returns(model, downgrade=None, upgrade=None)[source]

Return a decorator for methods that return instances of model.

Parameters
  • model – a model name, or 'self' for the current model
  • downgrade – a function downgrade(self, value, *args, **kwargs) to convert the record-style value to a traditional-style output
  • upgrade – a function upgrade(self, value, *args, **kwargs) to convert the traditional-style value to a record-style output

The arguments self, *args and **kwargs are the ones passed to the method in the record-style.

The decorator adapts the method output to the api style: id, ids or False for the traditional style, and recordset for the record style:

@model
@returns('res.partner')
def find_partner(self, arg):
    ...     # return some record

# output depends on call style: traditional vs record style
partner_id = model.find_partner(cr, uid, arg, context=context)

# recs = model.browse(cr, uid, ids, context)
partner_record = recs.find_partner(arg)

Note that the decorated method must satisfy that convention.

Those decorators are automatically inherited: a method that overrides a decorated existing method will be decorated with the same @returns(model).

Environment

The Environment stores various contextual data used by the ORM: the database cursor (for database queries), the current user (for access rights checking) and the current context (storing arbitrary metadata). The environment also stores caches.

All recordsets have an environment, which is immutable, can be accessed using env and gives access to:

  • the current user (