CRM — Odoo Business 0.1 documentation



在 8.0以后新增: 本文档的新API加入Odoo 8应该是初级开发API。它还提供有关移植或桥接 "旧 API" versions 7 甚至更早, but does not explicitly document that API. See the old documentation for that.


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 anywhere between 0 records and all records in the
        # database

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), ...


Recordsets provide an "Active Record" interface: model fields can be read and written directly from the record, but only on singletons (single-record recordsets). Setting a field's value triggers an update to the database:

Example Name
Company Name
>>> = "Bob"


访问关系域 (Many2one, One2many, Many2many) 总是 返回一个记录集,如果没有设置字段是空的.



记录.name             # first access reads value from database
记录.名称             # second access gets value from cache

为了避免每次调用数据都需要阅读记录,Odoo 预取 记录和一些启发式的领域,以获得良好的性能。一旦领域必须在给定的记录中读取,ORM实际上读取较大的字段记录集,并将返回值在以后使用缓存。预取记录集通常是记录,记录是由迭代。此外,所有简单的存储字段(布尔,整数,浮点,字符,文本,日期,日期时间、选择、many2one)取共;它们对应于模型表的列,并在同一查询中高效地获取 .

考虑下面的例子,在合作伙伴 是一个集1000记录.没有预取,循环将对数据库进行2000个查询。预取,只有一个查询

里的 合作伙伴 in partners:
    print          # first pass prefetches 'name' and 'lang'
                                # (and other fields) on all 'partners'
    print partner.lang

预取也适用于 二级记录: 当关系字段读取,他们的值(这是记录)订阅未来的预取。其中一次访问记录预取所有辅助记录同一模型。这使得下面的示例只生成两个查询,一个伙伴和国家:

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


记录集是不可变的,但同样的模型集可以组合使用各种设置操作,返回新的记录集。设置操作做 not preserve order.

  • record in set returns whether record (which must be a 1-element recordset) is present in set. record not in set is the inverse operation
  • set1 <= set2 and set1 < set2 return whether set1 is a subset of set2 (resp. strict)
  • set1 >= set2 and set1 > set2 return whether set1 is a superset of set2 (resp. strict)
  • set1 | set2 返回两个记录集的结合,一个新的记录包含在任一源中的所有记录
  • set1 & set2 返回两个记录集的交集,一个新的记录只包含两种来源的记录
  • set1 - set2 返回一个新的记录集只包含记录 set1 which are not in set2

Other recordset operations

Recordsets are iterable so the usual Python tools are available for transformation (map(), sorted(), ifilter(), ...) however these return either a list or an iterator, 去除能力 调用其结果的方法,或使用set操作.

因此,这些操作返回记录集记录集提供自己 (when possible):


returns a recordset containing only records satisfying the provided predicate function. The predicate can also be a string to filter by a field being true or false:

# only keep records whose company is the current user's
records.filtered(lambda r: r.company_id == user.company_id)

# only keep records whose partner is a company

returns a recordset sorted by the provided key function. If no key is provided, use the model's default sort order:

# sort records by name
records.sorted(key=lambda r:


# returns a list of summing two fields for each record in the set
records.mapped(lambda r: r.field1 + r.field2)

The provided function can be a string to get field values:

# returns a list of names

# returns a recordset of partners

# returns the union of all partner banks, with duplicates removed


The Environment 通过使用不同的上下文数据的商店在ORM数据库(数据库:游标查询当前用户)(适当的访问权限检查的当前上下文(储存)和任意元数据)。商店环境也缓存。

All recordsets have an environment, which is immutable, can be accessed using env and gives access to the current user (user), the cursor (cr) or the context (context):

>>> records.env
<Environment object ...>
>>> records.env.user
<Cursor object ...)

When creating a recordset from an other recordset, the environment is inherited. The environment can be used to get an empty recordset in an other model, and query that model:

>>> self.env['res.partner']
>>> self.env['res.partner'].search([['is_company', '=', True], ['customer', '=', True]])
res.partner(7, 18, 12, 14, 17, 19, 8, 31, 26, 16, 13, 20, 30, 22, 29, 15, 23, 28, 74)

Altering the environment

The environment can be customized from a recordset. This returns a new version of the recordset using the altered environment.



# create partner object as administrator
env['res.partner'].sudo().create({'name': "A Partner"})

# list partners visible by the "public" user
public = env.ref('base.public_user')
  1. can take a single positional parameter, which replaces the current environment's context
  2. 可以采取任意数量的参数的关键字,这是添加到当前环境的上下文或步骤1中设置的上下文
# look for partner, or create one with specified timezone if none is
# found
replaces the existing environment entirely

Common ORM methods


Takes a search domain, returns a recordset of matching records. Can return a subset of matching records (offset and limit parameters) and be ordered (order parameter):

>>> # searches the current model
>>>[('is_company', '=', True), ('customer', '=', True)])
res.partner(7, 18, 12, 14, 17, 19, 8, 31, 26, 16, 13, 20, 30, 22, 29, 15, 23, 28, 74)
>>>[('is_company', '=', True)], limit=1).name

Takes a number of field values, and returns a recordset containing the record created:

>>> self.create({'name': "New Name"})

Takes a number of field values, writes them to all the records in its recordset. Does not return anything:

self.write({'name': "Newer Name"})

Takes a database id or a list of ids and returns a recordset, useful when record ids are obtained from outside Odoo (e.g. round-trip through external system) or when calling methods in the old API:

>>> self.browse([7, 18, 12])
res.partner(7, 18, 12)


if not record.exists():
    raise Exception("The record has been deleted")


# only keep records which were not deleted
records = records.exists()

Environment method returning the record matching a provided external id:

>>> env.ref('base.group_public')

checks that the recordset is a singleton (only contains a single record), raises an error otherwise:

# is equivalent to but clearer than:
assert len(records) == 1, "Expected singleton"

Creating Models

Model fields are defined as attributes on the model itself:

from odoo import models, fields
class AModel(models.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="an other field")

For the various field types and parameters, see the fields reference.

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

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

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

def compute_default_value(self):
    return self.get_value()
a_field = fields.Char(default=compute_default_value)

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.value + record.value *
  • dependencies can be dotted paths when using sub-fields:

    def _compute_total(self):
        for record in self:
   = sum(line.value for line in record.line_ids)
  • 计算字段不默认存储,它们是计算和请求时返回。设置 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 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)]
  • 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 =
    def _set_document(self):
        for record in self:
            if not record.document: continue
            with open(record.get_document_path()) as f:
  • 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')
    @depends('value', 'discount')
    def _apply_discount(self):
        for record in self:
            # compute actual discount from discount percentage
            discount = record.value *
            record.discount_value = discount
   = record.value - discount

onchange: updating UI on the fly


  • computed fields are automatically checked and recomputed, they do not need an onchange
  • for non-computed fields, the onchange() decorator is used to provide new field values:

    @api.onchange('field1', 'field2') # if these fields are changed, call method
    def check_change(self):
        if self.field1 < self.field2:
            self.field3 = True

    the changes performed during the method are then sent to the client program and become visible to the user

  • Both computed fields and new-API onchanges are automatically called by the client without having to add them in views
  • It is possible to suppress the trigger from a specific field by adding on_change="0" in a view:

    <field name="name" on_change="0"/>

    will not trigger any interface update when the field is edited by the user, even if there are function fields or explicit onchange depending on that field.

Low-level SQL

The cr 环境属性是当前数据库事务的游标,并允许直接执行sql,对于使用ORM难以表达的查询 (e.g. complex joins) or for performance reasons:"some_sql", param1, param2, param3)

Because models use the same cursor and the Environment holds various caches, these caches must be invalidated when altering the database in raw SQL, or further uses of models may become incoherent. It is necessary to clear caches when using CREATE, UPDATE or DELETE in SQL, but not SELECT (which simply reads the database).

Clearing caches can be performed using the invalidate_all() method of the Environment object.

Compatibility between new API and old API

Odoo is currently transitioning from an older (less regular) API, it can be necessary to manually bridge from one to the other manually:

  • RPC layers (both XML-RPC and JSON-RPC) are expressed in terms of the old API, methods expressed purely in the new API are not available over RPC
  • overridable methods may be called from older pieces of code still written in the old API style

The big differences between the old and new APIs are:

  • values of the Environment (cursor, user id and context) are passed explicitly to methods instead
  • record data (ids) are passed explicitly to methods, and possibly not passed at all
  • methods tend to work on lists of ids instead of recordsets

By default, methods are assumed to use the new API style and are not callable from the old API style.

Two decorators can expose a new-style method to the old API:


the method is exposed as not using ids, its recordset will generally be empty. Its "old API" signature is cr, uid, *arguments, context:

def some_method(self, a_value):
# can be called as
old_style_model.some_method(cr, uid, a_value, context=context)

the method is exposed as taking a list of ids (possibly empty), its "old API" signature is cr, uid, ids, *arguments, context:

def some_method(self, a_value):
# can be called as
old_style_model.some_method(cr, uid, [id1, id2], a_value, context=context)

Because new-style APIs tend to return recordsets and old-style APIs tend to return lists of ids, there is also a decorator managing this:


the function is assumed to return a recordset, the first parameter should be the name of the recordset's model or self (for the current model).

No effect if the method is called in new API style, but transforms the recordset into a list of ids when called from the old API style:

>>> @api.multi
... @api.returns('self')
... def some_method(self):
...     return self
>>> new_style_model = env['a.model'].browse(1, 2, 3)
>>> new_style_model.some_method()
a.model(1, 2, 3)
>>> old_style_model = pool['a.model']
>>> old_style_model.some_method(cr, uid, [1, 2, 3], context=context)
[1, 2, 3]


class odoo.models.Model(pool, cr)[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).

Structural attributes


business object name, in dot-notation (in module namespace)


Alternative field to use as name, used by osv’s name_get() (default: 'name')

  • If _name is set, names of parent models to inherit from. Can be a str if inheriting from a single parent
  • If _name is unset, name of a single model to extend in-place

See Inheritance and extension.


Ordering field when searching without an ordering specified (default: 'id')


Whether a database table should be created (default: True)

If set to False, override init() to create the database table


Name of the table backing the model created when _auto, automatically generated by default.


dictionary 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 _inherits-ed model but stores none of them: the values themselves remain stored on the linked record.


list of (constraint_function, message, fields) defining Python constraints. The fields list is indicative

Deprecated since version 8.0: use constrains()


list of (name, sql_definition, message) triples defining SQL constraints to execute when generating the backing table


Alongside parent_left and parent_right, sets up a nested set to enable fast hierarchical queries on the records of the current model (default: False)



create(vals) → record[source]

Creates a new record for the model.

The new record is initialized using the values from vals and if necessary those from default_get().

vals (dict) --

values for the model's fields, as a dictionary:

{'field_name': field_value, ...}

see write() for details

new record created
  • AccessError --
    • if user has no create rights on the requested object
    • if user tries to bypass access rules for create on the requested object
  • ValidateError -- if user tries to enter invalid value for a field that is not in selection
  • UserError -- if a loop would be created in a hierarchy of objects a result of the operation (such as setting an object as its own parent)
browse([ids]) → records[source]

Returns a recordset for the ids provided as parameter in the current environment.

Can take no ids, a single id or a sequence of ids.

Deletes the records of the current set

  • AccessError --
    • if user has no unlink rights on the requested object
    • if user tries to bypass access rules for unlink on the requested object
  • UserError -- if the record is default property for other records

Updates all records in the current set with the provided values.

vals (dict) --

fields to update and the value to set on them e.g:

{'foo': 1, 'bar': "Qux"}

will set the field foo to 1 and the field bar to "Qux" if those are valid (otherwise it will trigger an error).

  • AccessError --
    • if user has no write rights on the requested object
    • if user tries to bypass access rules for write on the requested object
  • ValidateError -- if user tries to enter invalid value for a field that is not in selection
  • UserError -- if a loop would be created in a hierarchy of objects a result of the operation (such as setting an object as its own parent)
  • For numeric fields (Integer, Float) the value should be of the corresponding type
  • For Boolean, the value should be a bool
  • For Selection, the value should match the selection values (generally str, sometimes int)
  • For Many2one, the value should be the database identifier of the record to set
  • Other non-relational fields use a string for value

  • One2many and Many2many use a special "commands" format to manipulate the set of records stored in/associated with the field.

    This format is a list of triplets executed sequentially, where each triplet is a command to execute on the set of records. Not all commands apply in all situations. Possible commands are:

    (0, _, values)
    adds a new record created from the provided value dict.
    (1, id, values)
    updates an existing record of id id with the values in values. Can not be used in create().
    (2, id, _)
    removes the record of id id from the set, then deletes it (from the database). Can not be used in create().
    (3, id, _)
    removes the record of id id from the set, but does not delete it. Can not be used on One2many. Can not be used in create().
    (4, id, _)
    adds an existing record of id id to the set. Can not be used on One2many.
    (5, _, _)
    removes all records from the set, equivalent to using the command 3 on every record explicitly. Can not be used on One2many. Can not be used in create().
    (6, _, ids)
    replaces all existing records in the set by the ids list, equivalent to using the command 5 followed by a command 4 for each id in ids.

Reads the requested fields for the records in self, low-level/RPC method. In Python code, prefer browse().

fields -- list of field names to return (default is all fields)
a list of dictionaries mapping field names to their values, with one dictionary per record
AccessError -- if user has no read rights on some of the given records
read_group(domain, fields, groupby, offset=0, limit=None, orderby=False, lazy=True)[source]

Get the list of records in list view grouped by the given groupby fields

  • domain -- list specifying search criteria [['field_name', 'operator', 'value'], ...]
  • fields (list) -- list of fields present in the list view specified on the object
  • groupby (list) -- 通过描述列表的记录将被分组。一组描述是一场(然后将字段分组)或一个字符串”字段:groupby_function”。现在,支持的唯一功能是“天”、“周”、“月”、“季”或“年”,它们只对日期/时间字段。
  • offset (int) -- optional number of records to skip
  • limit (int) -- optional max number of records to return
  • orderby (list) -- optional order by specification, for overriding the natural sort ordering of the groups, see also search() (supported only for many2one fields currently)
  • lazy (bool) -- if true, the results are only grouped by the first groupby and the remaining groupbys are put in the __context key. If false, all the groupbys are done in one call.

list of dictionaries(one dictionary for each record) containing:

  • the values of fields grouped by the fields in groupby argument
  • __domain: list of tuples specifying the search criteria
  • __context: dictionary with argument like groupby
Return type
[{'field_name_1': value, ...]
AccessError --
  • if user has no read rights on the requested object
  • if user tries to bypass access rules for read on the requested object


search(args[, offset=0][, limit=None][, order=None][, count=False])[source]

Searches for records based on the args search domain.

  • args -- A search domain. Use an empty list to match all records.
  • offset (int) -- number of results to ignore (default: none)
  • limit (int) -- maximum number of records to return (default: all)
  • order (str) -- sort string
  • count (bool) -- if True, only counts and returns the number of matching records (default: False)
at most limit records matching the search criteria
AccessError --
  • if user tries to bypass access rules for read on the requested object.
search_count(args) → int[source]

Returns the number of records in the current model matching the provided domain.

Search for records that have a display name matching the given name pattern when compared with the given operator, while also matching the optional search domain (args).

This is used for example to provide suggestions based on a partial value for a relational field. Sometimes be seen as the inverse function of name_get(), but it is not guaranteed to be.

This method is equivalent to calling search() with a search domain based on display_name and then name_get() on the result of the search.

  • name (str) -- the name pattern to match
  • args (list) -- optional search domain (see search() for syntax), specifying further restrictions
  • operator (str) -- domain operator for matching name, such as 'like' or '='.
  • limit (int) -- optional max number of records to return
Return type
list of pairs (id, text_repr) for all matching records.

Recordset operations


List of actual record ids in this recordset (ignores placeholder ids for records to create)


Verifies that the current recorset holds a single record. Raises an exception otherwise.

exists() → records[source]

Returns the subset of records in self that exist, and marks deleted records as such in cache. It can be used as a test on records:

if record.exists():

By convention, new records are returned as existing.


Select the records in self such that func(rec) is true, and return them as a recordset.

func -- a function or a dot-separated sequence of field names
sorted(key=None, reverse=False)[source]

Return the recordset self ordered by key.

  • key -- either a function of one argument that returns a comparison key for each record, or a field name, or None, in which case records are ordered according the default model's order
  • reverse -- if True, return the result in reverse order

Apply func on all records in self, and return the result as a list or a recordset (if func return recordsets). In the latter case, the order of the returned recordset is arbitrary.

func -- a function or a dot-separated sequence of field names (string); any falsy value simply returns the recordset self

Environment swapping


Returns a new version of this recordset attached to the provided user.

By default this returns a SUPERUSER recordset, where access control and record rules are bypassed.

with_context([context][, **overrides]) → records[source]


The extended context is either the provided context in which overrides are merged or the current context in which overrides are merged e.g.:

# current context is {'key1': True}
r2 = records.with_context({}, key2=True)
# -> r2._context is {'key2': True}
r2 = records.with_context(key2=True)
# -> r2._context is {'key1': True, 'key2': True}

Returns a new version of this recordset attached to the provided environment

Fields and views querying

fields_get([fields][, attributes])[source]

Return the definition of each field.

The returned value is a dictionary (indiced by field name) of dictionaries. The _inherits'd fields are included. The string, help, and selection (if present) attributes are translated.

  • allfields -- list of fields to document, all if empty or not provided
  • attributes -- list of description attributes to return for each field, all if empty or not provided
fields_view_get([view_id | view_type='form'])[source]

Get the detailed composition of the requested view like fields, model, view architecture

  • view_id -- id of the view or None
  • view_type -- type of the view to return if view_id is None ('form', 'tree', ...)
  • toolbar -- true to include contextual actions
  • submenu -- deprecated
dictionary describing the composition of the requested view (including inherited views and extensions)
  • AttributeError --
    • if the inherited view has unknown position to work with other than 'before', 'after', 'inside', 'replace'
    • if some tag other than 'position' is found in parent view
  • Invalid ArchitectureError -- if there is view type other than form, tree, calendar, search etc defined on the structure

Miscellaneous methods

default_get(fields) → default_values[source]

Return default values for the fields in fields_list. Default values are determined by the context, user defaults, and the model itself.

fields_list -- a list of field names
a dictionary mapping each field name to its corresponding default value, if it has one.

Duplicate record self updating it with default values

default (dict) -- dictionary of field values to override in the original values of the copied record, e.g: {'field_name': overridden_value, ...}
new record
name_get() → [(id, name), ...][source]

Returns a textual representation for the records in self. By default this is the value of the display_name field.

list of pairs (id, text_repr) for each records
Return type
name_create(name) → record[source]

Create a new record by calling create() 只有一个值提供:新记录的显示名称.

新记录将用任何默认值初始化适用于此模型,或通过上下文提供。通常的行为 create() applies.

name -- display name of the record to create
Return type
the name_get() pair value of the created record

Automatic fields


Identifier field


Whether log access fields (create_date, write_uid, ...) should be generated (default: True)


Date at which the record was created


Relational field to the user who created the record


Date at which the record was last modified


Relational field to the last user who modified the record


Reserved field names



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


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


Alterable ordering criteria, allows drag-and-drop reordering of models in list views


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


used to order records in a tree structure and enables the child_of operator in domains


used with _parent_store, allows faster tree structure access


see parent_left

Method decorators

This module provides the elements for managing two different API styles, namely the "traditional" and "record" styles.

In the "traditional" style, parameters like the database cursor, user id, context dictionary and record ids (usually denoted as cr, uid, context, ids) are passed explicitly to all methods. In the "record" style, those parameters are hidden into model instances, which gives it a more object-oriented feel.

For instance, the statements:

model = self.pool.get(MODEL)
ids =, uid, DOMAIN, context=context)
for rec in model.browse(cr, uid, ids, context=context):
model.write(cr, uid, ids, VALUES, context=context)

may also be written as:

env = Environment(cr, uid, context) # cr, uid, context wrapped in env
model = env[MODEL]                  # retrieve an instance of MODEL
recs =         # search returns a recordset
for rec in recs:                    # iterate over the records
recs.write(VALUES)                  # update all records in recs

Methods written in the "traditional" style are automatically decorated, following some heuristics based on parameter names.


Decorate a record-style method where self is a recordset. The method typically defines an operation on records. Such a method:

def method(self, args):

may be called in both record and traditional styles, like:

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

model.method(cr, uid, ids, args, context=context)

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

def method(self, args):

may be called in both record and traditional styles, like:

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

model.method(cr, uid, args, context=context)

Notice that no ids are passed to the method in the traditional style.


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.is_company')
def _compute_pname(self):
    if self.partner_id.is_company:
        self.pname = ( or "").upper()
        self.pname =



Decorates a constraint checker. Each argument must be a field name used in the check:
@api.constrains('name', 'description')
def _check_description(self):
    if == self.description:
        raise ValidationError("Fields name and description must be different")


Should raise ValidationError if the validation failed.


Return a decorator to decorate an onchange method for given fields. Each argument must be a field name:

def _onchange_partner(self):
    self.message = "Dear %s" % ( or "")


return {
    'domain': {'other_id': [('partner_id', '=', partner_id)]},
    'warning': {'title': "Warning", 'message': "What is this?"},
odoo.api.returns(model, downgrade=None, upgrade=None)[source]

Return a decorator for methods that return instances of model.

  • 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 对于传统的风格,并作记录方式记录集:

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)


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

Decorate a record-style method where self 预计将是单实例。装饰方法自动循环记录,并列出结果。如果方法装饰 returns(), it concatenates the resulting instances. Such a method:
def method(self, args):

may be called in both record and traditional styles, like:

# recs = model.browse(cr, uid, ids, context)
names = recs.method(args)

names = model.method(cr, uid, ids, args, context=context)

在version 9.0后失效: one() 经常使代码不清晰和行为方式开发商和读者可能不指望.

It is strongly recommended to use multi() and either iterate on the self recordset or ensure that the recordset is a single record with ensure_one().


仅支持旧式API的装饰方法。一种新型的API可以通过重新定义具有相同名称和装饰的方法来提供具有 v8():

def foo(self, cr, uid, ids, context=None):

def foo(self):

如果一个方法调用另一个方法,必须特别小心,因为该方法可能被重写!在这种情况下,应该调用的方法从当前类 (say MyClass), for instance:

def foo(self, cr, uid, ids, context=None):
    # Beware: may call an overriding of foo()
    records = self.browse(cr, uid, ids, context)

Note that the wrapper method uses the docstring of the first method.


Decorate a method that supports the new-style api only. An old-style api may be provided by redefining a method with the same name and decorated with v7():

def foo(self):

def foo(self, cr, uid, ids, context=None):



Basic fields

class odoo.fields.Field(string=<object object>, **kwargs)[source]

字段描述符包含字段定义和管理访问记录对应字段的赋值。以下属性可以设置当instanciating一场 :

  • string -- the label of the field seen by users (string); if not set, the ORM takes the field name in the class (capitalized).
  • help -- the tooltip of the field seen by users (string)
  • readonly -- whether the field is readonly (boolean, by default False)
  • required -- whether the value of the field is required (boolean, by default False)
  • index -- whether the field is indexed in database (boolean, by default False)
  • default -- 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 -- 字典将状态值映射到UI属性值列表对;可能的属性:“只读”、“需要”、“看不见”。注:任何状态为基础的条件要求 state 字段值为可在客户端的UI。这通常包括在有关的意见,可能是无形的,如果不相关的最终用户.
  • groups -- comma-separated list of group xml ids (string); this restricts the field access to the users of the given groups only
  • 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)
  • oldname (string) -- the previous name of this field, so that ORM can rename it automatically at migration

Computed fields

我们可以定义一个字段,它的值是计算而不是简单的从数据库中读取。特定于计算的属性下面给出字段。要定义这样的字段,只需提供一个值该属性 compute.

  • compute -- name of a method that computes the field
  • inverse -- name of a method that inverses the field (optional)
  • search -- name of a method that implement search on the field (optional)
  • store -- whether the field is stored in database (boolean, by default False on computed fields)
  • compute_sudo -- whether the field should be recomputed as superuser to bypass access rights (boolean, by default False)

The methods given for compute, inverse and search are model methods. Their signature is shown in the following example:

upper = fields.Char(compute='_compute_upper',

def _compute_upper(self):
    for rec in self:
        rec.upper = if else False

def _inverse_upper(self):
    for rec in self: = rec.upper.lower() if rec.upper else False

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

计算方法必须在调用的所有记录上分配字段记录集。装饰 odoo.api.depends() 必须应用于指定字段依赖关系的计算方法;这些依赖项用于确定何时重新计算领域;重新自动和保证缓存/数据库一致性。注意相同方法可用于多个字段,您只需指定所有给定方法中的字段;该方法将为所有调用一次。这些领域.

默认情况下,计算字段不存储到数据库中,并且实时计算。添加属性 store=True 将存储字段在数据库中的值。存储字段的优点是在该字段的搜索是由数据库本身。的缺点是它需要更新数据库时,必须重新计算.


在处理域之前,会调用搜索方法模型上的实际搜索。它必须返回一个相当于条件: field operator value.


related -- sequence of field names

某些字段属性将从源字段自动复制,如果他们没有重新定义: string, help, readonly, required (only if all fields in the sequence are required), groups, digits, size, translate, sanitize, selection, comodel_name, domain, context. All semantic-free attributes are copied from the source field.

By default, the values of related fields are not stored to the database. Add the attribute store=True to make it stored, just like computed fields. Related fields are automatically recomputed when their dependencies are modified.

Company-dependent fields


company_dependent -- whether the field is company-dependent (boolean)

Sparse fields

Sparse fields have a very small probability of being not null. Therefore many such fields can be serialized compactly into a common location, the latter being a so-called "serialized" field.

sparse -- the name of the field where the value of this field must be stored.

Incremental definition

A field is defined as class attribute on a model class. If the model is extended (see Model), 也可以延长通过重新定义同名字段的字段定义子类类型。在这种情况下,字段的属性是从父类中获取,并在父类中重写子类。

例如,下面的第二类只在字段中添加工具提示 state:

class First(models.Model):
    _name = 'foo'
    state = fields.Selection([...], required=True)

class Second(models.Model):
    _inherit = 'foo'
    state = fields.Selection(help="Blah blah blah")
class odoo.fields.Char(string=<object object>, **kwargs)[source]

Bases: odoo.fields._String

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

  • size (int) -- the maximum size of values stored for that field
  • translate -- 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.Boolean(string=<object object>, **kwargs)[source]

Bases: odoo.fields.Field

class odoo.fields.Integer(string=<object object>, **kwargs)[source]

Bases: odoo.fields.Field

class odoo.fields.Float(string=<object object>, digits=<object object>, **kwargs)[source]

Bases: odoo.fields.Field

The precision digits are given by the attribute

digits -- a pair (total, decimal), or a function taking a database cursor and returning a pair (total, decimal)
class odoo.fields.Text(string=<object object>, **kwargs)[source]

Bases: odoo.fields._String

Very similar to Char 但用于较长的内容,不有一个大小和通常显示为多行文本框.

translate -- 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.Selection(selection=<object object>, string=<object object>, **kwargs)[source]

Bases: odoo.fields.Field

  • selection -- specifies the possible values for this field. It is given as either a list of pairs (value, string), or a model method, or a method name.
  • selection_add -- provides an extension of the selection in the case of an overridden field. It is a list of pairs (value, string).

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

class odoo.fields.Html(string=<object object>, **kwargs)[source]

Bases: odoo.fields._String

class odoo.fields.Date(string=<object object>, **kwargs)[source]

Bases: odoo.fields.Field

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. This method may be used to compute default values.

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
static from_string(value)[source]

Convert an ORM value into a date value.

static to_string(value)[source]

Convert a date value into the format expected by the ORM.

static today(*args)[source]


class odoo.fields.Datetime(string=<object object>, **kwargs)[source]

Bases: odoo.fields.Field

static context_timestamp(record, timestamp)[source]

返回给定时间戳转换为客户端的时区。 This method is not meant for use as a default initializer, because datetime fields are automatically converted upon display on client side. For default values should be used instead.

timestamp (datetime) -- naive datetime value (expressed in UTC) to be converted to the client timezone
Return type
timestamp converted to timezone-aware datetime in context timezone
static from_string(value)[source]

Convert an ORM value into a datetime value.

static now(*args)[source]

Return the current day and time in the format expected by the ORM. This function may be used to compute default values.

static to_string(value)[source]

Convert a datetime value into the format expected by the ORM.

Relational fields

class odoo.fields.Many2one(comodel_name=<object object>, string=<object object>, **kwargs)[source]

Bases: odoo.fields._Relational

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

  • comodel_name -- name of the target model (string)
  • domain -- 在候选值上设置的可选域客户端(域或字符串)
  • context -- an optional context to use on the client side when handling that field (dictionary)
  • ondelete -- what to do when the referred record is deleted; possible values are: 'set null', 'restrict', 'cascade'
  • auto_join -- whether JOINs are generated upon search through that field (boolean, by default False)
  • delegate -- set it to True to make fields of the target model accessible from the current model (corresponds to _inherits)

The attribute comodel_name is mandatory except in the case of related fields or field extensions.

class odoo.fields.One2many(comodel_name=<object object>, inverse_name=<object object>, string=<object object>, **kwargs)[source]

Bases: odoo.fields._RelationalMulti

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.

  • comodel_name -- name of the target model (string)
  • inverse_name -- name of the inverse Many2one field in comodel_name (string)
  • domain -- an optional domain to set on candidate values on the client side (domain or string)
  • context -- an optional context to use on the client side when handling that field (dictionary)
  • auto_join -- whether JOINs are generated upon search through that field (boolean, by default False)
  • limit -- optional limit to use upon read (integer)

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

class odoo.fields.Many2many(comodel_name=<object object>, relation=<object object>, column1=<object object>, column2=<object object>, string=<object object>, **kwargs)[source]

Bases: odoo.fields._RelationalMulti

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

comodel_name -- name of the target model (string)

The attribute comodel_name is mandatory except in the case of related fields or field extensions.

  • relation -- optional name of the table that stores the relation in the database (string)
  • column1 -- optional name of the column referring to "these" records in the table relation (string)
  • column2 -- optional name of the column referring to "those" records in the table relation (string)

The attributes relation, column1 and column2 是可选的。如果不是给定的,名称自动生成模型名称,提供 model_name and comodel_name are different!

  • domain -- an optional domain to set on candidate values on the client side (domain or string)
  • context -- an optional context to use on the client side when handling that field (dictionary)
  • limit -- optional limit to use upon read (integer)
class odoo.fields.Reference(selection=<object object>, string=<object object>, **kwargs)[source]

Bases: odoo.fields.Selection



  • 创建一个新的模型从现有的,添加新的信息复制,但离开原来的模块
  • 扩展模型定义在其他模块的地方,取代以前版本
  • delegating some of the model's fields to records it contains

Classical inheritance

When using the _inherit and _name attributes together, Odoo creates a new model using the existing one (provided via _inherit) as a base. The new model gets all the fields, methods and meta-information (defaults & al) from its base.

class Inheritance0(models.Model):
    _name = 'inheritance.0'

    name = fields.Char()

    def call(self):
        return self.check("model 0")

    def check(self, s):
        return "This is {} record {}".format(s,

class Inheritance1(models.Model):
    _name = 'inheritance.1'
    _inherit = 'inheritance.0'

    def call(self):
        return self.check("model 1")

and using them:

        env = self.env

will yield:

the second model has inherited from the first model's check method and its name field, but overridden the call method, as when using standard Python inheritance.


When using _inherit but leaving out _name, 新模式取代现有模式,基本上把它扩展到位。这对于添加新的字段或方法很有用对现有模型(在其他模块中创建),或自定义或重新配置它们(例如改变默认排序顺序):

class Extension0(models.Model):
    _name = 'extension.0'

    name = fields.Char(default="A")

class Extension1(models.Model):
    _inherit = 'extension.0'

    description = fields.Char(default="Extended")
        env = self.env
        {'name': "A", 'description': "Extended"}

will yield:


第三继承机制提供更大的灵活性 (它可以在运行时被改变) but less power: using the _inherits a model delegates the lookup of any field not found on the current model to "children" models. The delegation is performed via Reference fields automatically set up on the parent model:

class Child0(models.Model):
    _name = 'delegation.child0'

    field_0 = fields.Integer()

class Child1(models.Model):
    _name = 'delegation.child1'

    field_1 = fields.Integer()

class Delegating(models.Model):
    _name = 'delegation.parent'

    _inherits = {
        'delegation.child0': 'child0_id',
        'delegation.child1': 'child1_id',

    child0_id = fields.Many2one('delegation.child0', required=True, ondelete='cascade')
    child1_id = fields.Many2one('delegation.child1', required=True, ondelete='cascade')
        super(TestDelegation, self).setUp()
        env = self.env
        record = env['delegation.parent'].create({
            'child0_id': env['delegation.child0'].create({'field_0': 0}).id,
        # children fields can be looked up on the parent record directly
        env = self.env

will result in:

        self.assertEqual(record.field_1, 1)

and it's possible to write directly on the delegated field:


A domain is a list of criteria, each criterion being a triple (either a list or a tuple) of (field_name, operator, value) where:

field_name (str)
a field name of the current model, or a relationship traversal through a Many2one using dot-notation e.g. 'street' or ''
operator (str)

an operator used to compare the field_name with the value. Valid operators are:

equals to
not equals to
greater than
greater than or equal to
less than
less than or equal to
unset or equals to (returns true if value is either None or False, otherwise behaves like =)
matches field_name against the value pattern. An underscore _ in the pattern stands for (matches) any single character; a percent sign % matches any string of zero or more characters.
matches field_name against the %value% pattern. Similar to =like but wraps value with '%' before matching
not like
doesn't match against the %value% pattern
case insensitive like
not ilike
case insensitive not like
case insensitive =like
is equal to any of the items from value, value should be a list of items
not in
is unequal to all of the items from value

is a child (descendant) of a value record.

Takes the semantics of the model into account (i.e following the relationship field named by _parent_name).

variable type, must be comparable (through operator) to the named field

Domain criteria can be combined using logical operators in prefix form:

logical AND, default operation to combine criteria following one another. Arity 2 (uses the next 2 criteria or combinations).
logical OR, arity 2.

logical NOT, arity 1.


  • 秃列表的ID是在新的API中避免使用记录集,而不是
  • 仍然写入旧API的方法应该自动桥接ORM,不需要切换到旧API,只要调用它们就像他们是一个新的API方法。看到 Automatic bridging of old API methods for more details.
  • search() returns a recordset, no point in e.g. browsing its result
  • fields.related and fields.function are replaced by using a normal field type with either a related= or a compute= parameter
  • depends() on compute= methods must be complete, it must list all 计算方法领域和子字段使用.最好是有太多的依赖(将重新计算领域如果是不需要的)比不够(会忘记重新计算字段和值将不正确)
  • remove all onchange methods on computed fields. Computed fields are automatically re-computed when one of their dependencies is changed, and that is used to auto-generate onchange by the client
  • the decorators model() and multi() are for bridging when calling from the old API context, for internal or pure new-api (e.g. compute) they are useless
  • remove _default, replace by default= parameter on corresponding fields
  • if a field's string= is the titlecased version of the field name:

    name = fields.Char(string="Name")

    it is useless and should be removed

  • the multi= parameter does not do anything on new API fields use the same compute= methods on all relevant fields for the same result
  • provide compute=, inverse= and search= methods by name (as a string), this makes them overridable (removes the need for an intermediate "trampoline" function)
  • double check that all fields and methods have different names, there is no warning in case of collision (because Python handles it before Odoo sees anything)
  • the normal new-api import is from odoo import fields, models. If compatibility decorators are necessary, use from odoo import api, fields, models
  • avoid the one() decorator, it probably does not do what you expect
  • remove explicit definition of create_uid, create_date, write_uid and write_date fields: they are now created as regular "legitimate" fields, and can be read and written like any other field out-of-the-box
  • when straight conversion is impossible (semantics can not be bridged) or the "old API" version is not desirable and could be improved for the new API, it is possible to use completely different "old API" and "new API" implementations for the same method name using v7() and v8(). The method should first be defined using the old-API style and decorated with v7(), it should then be re-defined using the exact same name but the new-API style and decorated with v8().从旧API上下文调用将发送到第一个实现,并从新的API上下文调用被派遣到第二实施。一个实现可以调用(和经常通过切换上下文调用其他

  • uses of _columns or _all_columns should be replaced by _fields, which provides access to instances of new-style odoo.fields.Field instances (rather than old-style odoo.osv.fields._column).

    Non-stored computed fields created using the new API style are not available in _columns and can only be inspected through _fields

  • reassigning self in a method is probably unnecessary and may break translation introspection
  • Environment objects rely on some threadlocal state, which has to be set up before using them. It is necessary to do so using the odoo.api.Environment.manage() context manager when trying to use the new API in contexts where it hasn't been set up yet, such as new threads or a Python interactive environment:

    >>> from odoo import api, modules
    >>> r = modules.registry.RegistryManager.get('test')
    >>> cr = r.cursor()
    >>> env = api.Environment(cr, 1, {})
    Traceback (most recent call last):
    AttributeError: environments
    >>> with api.Environment.manage():
    ...     env = api.Environment(cr, 1, {})
    ...     print env['res.partner'].browse(1)



Methods are matched as "old-API style" if their second positional parameter (after self) is called either cr or cursor. The system also recognizes the third positional parameter being called uid or user and the fourth being called id or ids. It also recognizes the presence of any parameter called context.

When calling such methods from a new API context, the system will automatically fill matched parameters from the current Environment (for cr, user and context) or the current recordset (for id and ids).

In the rare cases where it is necessary, the bridging can be customized by decorating the old-style method:

  • disabling it entirely, by decorating a method with noguess() 将不会有桥梁和方法将调用完全相同的方式从新的和旧的API风格
  • 明确定义桥,这主要是为匹配的方法 错误(因为参数以意外的方式命名):



    所有的方法都有_context-suffixed version (e.g. cr_uid_context()) which also passes the current context by keyword.

  • dual implementations using v7() and v8() will be ignored as they provide their own "bridging"