Odoo 13开发者文档：ORM API

本文来自Odoo 13官方文档之开发者文档系列文章

对象关系模块:

• 等级结构
• 约束一致性及验证
• 对象元数据取决于其状态
• 由复杂查询优化的进程(同时处理多个动作)
• 默认字段值
• 权限优化
• 持久化对象: DB postgresql
• 数据转换
• 多级缓存系统
• 两种不同的继承机制

• 字段类型的丰富集合：

  • 经典类型(varchar, integer, boolean, …)
  • 关联类型 (one2many, many2one, many2many)
  • 函数式类型

模型

模型字段在模型本身中以属性来进行定义：

默认，字段的标签（用户可见的名称）为字段名的首字母大写，这可通过 string 参数来进行重写。

字段类型及参数列表可参见字段指南。

默认值是对字段定义的参数，可以是一个值：

也可以调用计算默认值的函数，该函数应返回一个值：

API

抽象模型

模型

过渡（临时）模型

字段

基本字段

高级字段

日期（时间）字段

Dates和Datetime是任何类型业务应用中都非常重要的字段，它们在常用的Odoo应用如物流或会计中都有被重度的使用，并且误用会导致不易察觉且有会很让人痛苦的bug，本部分旨在向 Odoo开发者提供用于避免误用这些字段的知识。

在将一个值赋给Date/Datetime字段时，有如下有效选项：

• date或datetime对象。
• 针对各字段一个适当的服务端格式字符串，Date字段为 (YYYY-MM-DD) ，Datetime字段为(YYYY-MM-DD HH:MM:SS)。
• False 或 None.

Date和Datetime字段类有帮助方法尝试将值转化为兼容的类型： to_date() 将会转化为一个datetime.date 对象，而to_datetime() 将转化为 datetime.datetime.

Date / Datetime 比较的最佳实践：

• Date字段仅能与date对象进行比较。
• Datetime字段仅能与datetime对象进行比较。

日期及日期时间的常用操作，如加、减或获取一段时间的开始/结束通过 Date 和 Datetime对外暴露。这些帮助类也可以通过导入 odoo.tools.date_utils来进行使用。

关联字段

伪关联字段

计算字段

可使用 compute 参数来计算（除直接从数据库中读取外）字段。必须对该字段分配计算的值。如果使用其它字段值，应当指定这些字段使用 depends()。

• 在使用子字段时依赖可以为带点的路径：
  @api.depends('line_ids.value') def _compute_total(self): for record in self: record.total = sum(line.value for line in record.line_ids)

  1 2 3 4

  @api.depends('line_ids.value') def _compute_total(self):     for record in self:         record.total = sum(line.value for line in record.line_ids)

• 计算字段默认不存储，而是在请求时进行计算并返回。设置 store=True 会将它们存储到数据库中并自动启用搜索。
• 对计算字段的搜索也可通过设置search 参数来进行启用。值为返回搜索域的一个方法名。
  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)]

  1 2 3 4 5 6

  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)]

  在对模型进行实际搜索前处理域时会调用搜索方法。它必须返回等价于 域运算符值条件的域。

• 计算字段默认为只读。要允许对计算字段设置值，应使用 inverse 参数。它是一个反向计算及设置关联字段的函数名：
  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)

  1 2 3 4 5 6 7 8 9 10 11

  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)

• 同一方法可在同时计算多个字段，只需对所有字段使用同一方法并对它们进行设置：
  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

  1 2 3 4 5 6 7 8 9 10

  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

关联字段

计算字段的一种特殊情况是关联(代理)字段，它提供当前记录的子字段值。它们通过设置related 参数进行定义并可以像普通字段那样进行存储：

关联字段的值通过遵循关联字段序列及读取所触达模型的字段来给定。待遍历的完整字段序列由 related 属性进行指定。

有些字段属性在未重新定义时从源字段中进行拷贝： string, help, readonly, required (仅在要求序列中所有字段时使用), groups, digits, size, translate, sanitize, selection, comodel_name, domain, context。所有无语名的属性都从源字段中拷贝。

默认，关联字段的值不在数据库中存储。和计算字段类似，添加 store=True 属性来对其进行存储。关联字段在修改依赖时会自动重新计算。

自动化字段

保留字段名

有些字段是为自动化字段之上的预定义行为所预留的。应当在要求关联行为时在模型中进行定义：

记录集

与模型和记录之间的交互通过记录集执行，它是一个相同模型记录的已排序集合。

对记录集的遍历会产生单记录（singletons）的新集合，很像遍历Python中单个字符的string字段字符串:

段访问

记录集提供一个“Active Record”接口：模型字段可直接从记录中读取为属性。

字段值也可像字典项那样进行访问， 对于动态字段名这样会比getattr()更为优雅、更为安全。 设置字段值会触发数据库中的更新：

记录缓存和预提取

Odoo对记录值维护一个缓存，这样不是每个字段访问都会进行数据库请求，那样会影响性能。以下示例在第一条语句时仅查询数据库：

为避免一次只读取一条记录的一个字段，Odoo按照获取良好性能的启发预抓取记录和字段。一旦需要对给定记录进行读取，ORM会实际对更大记录集读取该字段，并返回值给缓存中存储供稍后使用。预抓取的记录集通常是来自遍历的记录。此外所有的简单存储字段 (boolean, integer, float, char, text, date, datetime, selection, many2one) 都同时进行获取；它们分别对应模型数据表中的字段，并在同一条查询中进行有效获取。

看下如下示例，其中 partners 是一个拥有1000条记录的记录集。不使用预提取的话，这个循环会对数据库进行 2000 次查询。而使用预提取时仅会做一次查询：

预提取也可用于二级记录； 在读取关联字段时，它们的值（即记录）用于未来的预提取。访问这些二级记录中的记录会提取同一模型中的所有二级记录。这样下例中仅会生成两条查询，分别用于partners 和countries:

方法装饰器

Odoo API模块定义Odoo环境及方法装饰器。

Environment

Environment 存储各种由 ORM 所使用的上下文数据：数据库游标(用于数据库查询)、当前用户 (用于访问权限检查) 及当前上下文 (存储任意metadata)。环境中还存储缓存。

所有的记录集都有一个环境，它是不可变的，可使用env 进行访问并授权给：

• 当前用户(user)
• 游标 (cr)
• 超级用户标记 (su)
• 或上下文(context)

在通过其它记录集创建记录集时，会继承其环境。environment可用于在其它模型中获取空记录集，并查询该模型：

更改environment

SQL执行

环境中的 cr 属性是当前数据库事务的游标，允许直接执行SQL，可能是难于使用 ORM 表达的查询 (如复杂的 join)或出于性能原因：

因为名模型使用同一个游标并且 Environment 存储各种缓存，这些缓存必须在数据库原生 SQL 修改数据库时置为无效，否则模型的进一步使用可能会产生不一致性。有必要在SQL使用CREATE, UPDATE 或 DELETE 时清除缓存，但无需对 SELECT进行此操作 (它只是读取了数据库)。

常用ORM方法

Create/update

Search/Read

字段/视图

搜索作用域

作用域一个条件列表，每个条件由(field_name, operator, value)三个元素组成 (可以是 列表 或  元组) ：

• field_name (str)

  当前模型的字段名，或通过Many2one使用点号标记的关联遍历，如 'street' 或 'partner_id.country'

• operator (str)

  用于比较 field_name 和 value的运算符。有效运算符有：

  =

  等于

  !=

  不等于

  >

  大于

  >=

  大于等于

  <

  小于

  <=

  小于等于

  =?

  未设置或等于 (若value 为None 或 False返回true，否则类似 =)

  =like

  通过value模式匹配 field_name。样式中的下划线 _ 表示（匹配）任意单个字符；百分号 % 匹配任意包含零个或多个字符的字符串。

  like

  通过%value%模式匹配 field_name 。类似于 =like ，但在匹配前通过‘%’包裹 value

  not like

  不匹配 %value% 模式

  ilike

  不区分大小写的 like

  not ilike

  不区分大小写的 not like

  =ilike

  不区分大小写的 =like

  in

  等于value中的任意项， value 应为一个列表

  not in

  不等于 value中的所有项

  child_of

  是 value 记录的后代(值可为单项或列表)。

  考虑模型的句法(如按照_parent_name所命名的关联字段)。

  parent_of

  value 记录的父级（先辈）(值可为单项或列表)。

  考虑模型的句法(如按照_parent_name所命名的关联字段)。

• value

  变量类型，必须可与命名字段(通过 运算符)相比较。

域条件可使用前缀形式的逻辑运算符进行合并：

'&'

逻辑与， 合并相连条件的默认运算。Arity 2 (使用接下来的两个条件或组合)。

'|'

逻辑或, arity 2.

'!'

逻辑非, arity 1.

大多针对条件组合取反。单个条件通常有一个取反形式(如 = -> !=, < -> >=) ，比对正值取负值更为简单。

Unlink

记录（集）信息

运算

记录集是不可变的，但相同模型的集合可使用各种集合运算符进行合并，返回一个新的记录集。

• record in set 返回 record (必须是一个元素的记录集) 是否在set中。record not in set 是其反向操作
• set1 <= set2 和 set1 < set2 返回set1 是否为 set2 的子集(resp. strict)
• set1 >= set2 和 set1 > set2 返回 set1 是否为 set2 的超集(resp. strict)
• set1 | set2 返回两个记录集的并集，新记录集中你居然说两个鹰中的所有记录
• set1 & set2 返回两个记录集的交集，新记录集中仅包含两个集合中同时出现的记录
• set1 - set2 仅返回属于 set1 但不属于 set2的记录的记录集

记录集是可迭代对象，因此常用的Python工具（(map(), sorted(), itertools.ifilter, …) ）均可用于转换，但这些会返回一个 列表 或时 迭代器，去除掉对结果调用方法或使用集合运算的功能。

因此记录集（在可用时）提供如下返回记录集本身的运算：

过滤

映射

排序

继承和扩展

Odoo提供三种不同的机制来以模块化的方式继承模型：

• 从已有模型新建一个模型，对复制的模型新增信息，但保留原模块为原样
• 在原处继承模块中定义的模型，替换原来的版本
• 你本来就是该模型的一些字段为它包含的记录

经典继承

在共同使用_inherit 和 _name 属性时， Odoo使用已有模型（通过_inherit）作为基础新建一个模型。新模型从基础获取所有字段、方法及元信息(defaults & al) 。

并使用它们：

会产生：

第二个模型从第一个模型的 check 方法及name字段中继承，但重载 call 方法，像使用标准Python 继承一样。

扩展

在使用 _inherit 但保留 _name时，新模型替换已有模型，基本是在原地进行扩展。这对于向（其它模块中所创建的）已有模型新增字段或方法、或是自定义或重新配置它们（例如修改默认排序）都非常有用：

会生成：

代理 

第三种继承机制提供更丰富的灵活性（可在运行时进行修改），但功能更少；使用 _inherits 模型代理当前模型中未找到的任意字段查询到“子”模型中。代理通过 Reference 字段自动在父级模型中设置。

最主要的区别是，在使用代理时，模型拥有它而非是它，转换组合中的关联而非继承：

会生产结果：

并且可以直接对代理字段进行写入：

字段递增定义

字段在模型类中定义为类属性。如果继承了模型，可以通过对子类重新使用相同名称和相同类型重新定义字段来扩展字段的定义。这时，字段的属性取自父类并由子类所指定的内容重载。

例如，下面的第二个类只会对state字段添加提示信息：

错误管理

Odoo异常模块定义了一些核心异常类型。

这些类型可被RPC层所解释。任意其它异常类在到达 RPC 前会被视为‘服务错误’。