ORM API（三）

搜索

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

  基于参数搜索记录

参数：  args：-- 搜索域，如果为空则匹配所有记录
     offset(int): – 默认要忽视的结果数量 （默认为None）
     limit(int): – 返回最大限定数量的记录（默认为全部）
     order(string): – 按照字段进行排序
     count(bool): – 如果为真，则返回匹配到记录的数量，默认为false
返回值：  根据限定条件匹配到的所有记录

search_count(args) → int

  返回当前模型根据搜索条件所匹配的记录数

name_search(name=’’, args=None, operator=‘ilike’, limit=100) → records

• 模糊匹配与给定name符合的名称的记录，并且也符合搜索域
• 可以为关系字段提供某些限定条件，有时被看做name_get()的逆函数，但不能保证。
• 这个方法相当于使用基于display_name的搜索域调用search()，然后根据搜索结果调用name_get()。

参数：  name(str)：-- 需要匹配的名称模式
     args(list): – 可选的搜索域(语法参见search())，指定进一步的限制
     operator (str): – 用于匹配名称的域操作符，如“like”或“=”
     limit (int) : – 可选的最大记录返回数
返回类型：  list
返回值： 所有匹配记录的对列表(id, text_repr)。

记录集操作

ids

此记录集中实际记录id的列表(忽略要创建的记录的占位符id)

ensure_one()

验证当前记录集是否包含单个记录。否则引发异常。

exists() → records

返回self中存在的记录的子集，并在缓存中将已删除的记录标记为已删除记录。它可以用来测试记录:

if record.exists():
    ...

按照惯例，新记录作为现有记录返回。

filtered(func)

选择func(rec)为真的记录，返回一个记录集

参数： func – 字段名的函数或点分隔序列

sorted(key=None, reverse=False)

返回通过key排序的记录集

参数：key – 一个参数的函数，返回每个记录的比较键，或者一个也不返回，在这种情况下，记录是按照默认模型的顺序排序的
   reverse – if True，倒序返回结果

mapped(func)

在self中的所有记录上应用func，并以列表或记录集的形式返回结果(如果func返回记录集)。在后一种情况下，返回记录集的顺序是任意的。

参数： func – 字段名的函数或点分隔序列

环境切换

sudo([user=SUPERUSER])

返回附加到所提供用户的此记录集的新版本。
默认情况下，它返回一个[未知节点title_reference]记录集，其中绕过了访问控制和记录规则。

使用[未知的节点title_reference]可能会导致数据访问跨越记录规则的边界，可能会混合要隔离的记录(例如来自多公司环境中不同公司的记录)。
它可能会导致在许多方法中选择一条记录的不直观结果——例如获得默认公司，或选择材料清单。

由于必须重新评估记录规则和访问控制，因此新记录集不能从当前环境的数据缓存中获益，因此，在从数据库重新获取数据时，稍后的数据访问可能会导致额外的延迟。

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

返回附加到扩展上下文的此记录集的新版本。
扩展上下文可以是合并覆盖的所提供的上下文，也可以是合并覆盖的当前上下文

# 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}

with_env(env)

返回附加到所提供环境的此记录集的新版本

新环境将无法从当前环境的数据缓存中获益，因此在从数据库重新获取数据时，稍后的数据访问可能会导致额外的延迟。

字段和试图查询

fields_get([fields][, attributes])

返回每一个字段的定义
返回的值是字典的字典(由字段名指示)。包含_inherits的字段。字符串、帮助和选择(如果存在)属性被转换

参数： allfields – 要记录的字段的列表，如果为空或未提供，则全部列出
   attributes – 为每个字段返回的描述属性列表，如果为空或未提供，则全部返回

fields_view_get([view_id | view_type=‘form’])

获取所请求视图的详细组合，如字段、模型、视图体系结构

参数：view_id – 视图的id或无
   view_type – 如果view_id为空，返回的视图类型(‘form’， ‘tree’，…)
   toolbar – true包含上下文操作
返回值：描述所请求视图的组合(包括继承视图和扩展)的字典
Raises: RttributeError–
   如果继承的视图除了“before”、“after”、“inside”之外还有未知的位置可以使用，则使用“replace”
   如果在父视图中找到“位置”以外的标记
   无效的体系结构错误——如果在结构上定义的视图类型不是表单、树、日历、搜索等

default_get(fields) → default_values

返回fields_list中字段的默认值。默认值由上下文、用户默认值和模型本身决定。

参数： fields_list – 字段名称列表
返回值：字典将每个字段名映射到对应的默认值(如果有的话)。

copy(default=None)

使用给定id用默认值更新记录的重复记录

参数： default (dict) – 要在复制记录的原始值中重写的字段值字典，例如:{‘field_name’: overridden_value, …}
返回值：新记录

name_get() → [(id, name), …]

返回self中记录的文本表示形式。默认情况下，这是display_name字段的值。

返回值：每个记录的对列表(id, text_repr)
返回类型：列表（元组）

name_create(name) → record

通过调用Create()创建一条新记录，只提供一个值:新记录的显示名称。
新记录将使用适用于此模型的任何默认值初始化，或通过上下文提供。应用create()的通常行为。

参数： name – 显示要创建的记录的名称
返回类型：元组
返回值：所创建记录的name_get()对值

自动字段

id

标识字段

_log_access

是否应该生成日志访问字段(create_date, write_uid，…)(默认值:True)

create_date

记录创建的日期

类型：Datetime

create_uid

创建记录的用户的关系字段

类型：res.users

write_date

记录最后一次修改的日期

类型：Datetime

write_uid

到最后一个修改记录的用户的关系字段

类型：res.users

保留字段名称

一些字段名保留给自动化字段之外的预定义行为。当需要相关行为时，它们应该在模型上定义:

name

_rec_name的默认值，用于在需要使用代表“命名”的上下文中显示记录。

类型：Char

active

切换记录的全局可见性，如果活动设置为False，则在大多数搜索和列表中记录是不可见的

类型：Boolean

sequence

可更改的排序条件，允许在列表视图中拖放模型的重新排序

类型：Integer

state

对象的生命周期阶段，由字段上的状态属性使用

类型：Selection

parent_id

用于对树结构中的记录进行排序，并在域中启用child_of操作符

类型：Many2one

parent_left

与_parent_store一起使用，允许更快的树结构访问

parent_right

与_parent_store一起使用，允许更快的树结构访问

方法修饰符

这个模块提供了管理两种不同的API样式的元素，即“传统”和“记录”样式。
在“传统”样式中，像数据库游标、用户id、上下文字典和记录id(通常表示为cr、uid、上下文、id)这样的参数显式地传递给所有方法。在“记录”样式中，这些参数隐藏在模型实例中，这使其具有更面向对象的感觉。
例如，这些语句:

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

也可以写成:

env = Environment(cr, uid, context) # cr, uid, context wrapped in env
model = env[MODEL]                  # 检索模型的实例
recs = model.search(DOMAIN)         # 搜索返回一个记录集
for rec in recs:                    # 遍历记录
    print rec.name
recs.write(VALUES)                  # 更新recs中的所有记录

使用“传统”风格编写的方法将自动修饰，并遵循一些基于参数名称的启发式方法。

openerp.api.multi(method)

装饰一个记录样式的方法，其中self是一个记录集。该方法通常定义对记录的操作。这样一个方法:

@api.multi
def method(self, args):
    ...

可以在记录和传统风格中调用，如:

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

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

openerp.api.model(method)

装饰一个记录样式的方法，其中self是一个记录集，但是它的内容不相关，只有模型相关。这样一个方法:

@api.model
def method(self, args):
    ...

可以在记录和传统风格中调用，如:

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

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

注意，在传统样式中没有向方法传递id。

openerp.api.depends(*args)

返回一个装饰器，该装饰器指定“compute”方法的字段依赖项(对于新样式的函数字段)。每个参数必须是一个字符串，由字段名的点分隔序列组成:

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

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

也可以将单个函数作为参数传递。在这种情况下，依赖关系是通过使用字段的模型调用函数来给出的。

openerp.api.constrains(*args)

修饰约束检查器。每个参数必须是一个字段名使用在检查:

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

在已修改其中一个命名字段的记录上调用。
如果验证失败，应该引发ValidationError。

@constrains只支持简单的字段名，不支持点名称(关系字段的字段，例如partner_id.customer)，并且将被忽略

openerp.api.onchange(*args)

返回装饰器来装饰给定字段的onchange方法。每个参数必须是一个字段名:

@api.onchange('partner_id')
def _onchange_partner(self):
    self.message = "Dear %s" % (self.partner_id.name or "")

在字段出现的表单视图中，当修改某个给定字段时将调用该方法。该方法是在包含表单中出现的值的伪记录上调用的。记录上的字段分配将自动发送回客户机。

该方法可能返回一个用于更改字段域的字典，并弹出一条警告消息，如在旧的API中:

return {
    'domain': {'other_id': [('partner_id', '=', partner_id)]},
    'warning': {'title': "Warning", 'message': "What is this?"},
}

@onchange只支持简单的字段名，不支持点名称(关系字段的字段，例如partner_id.tz)，将被忽略

openerp.api.returns(model, downgrade=None, upgrade=None)

为返回模型实例的方法返回装饰器。

参数：model – 当前模型的模型名称或“self”
   downgrade – 函数降级(self、value、*args、**kwargs)，将记录样式的值转换为传统样式的输出
   upgrade – 函数升级(self、value、*args、**kwargs)，将传统样式的值转换为记录样式的输出

self、*args和**kwargs参数是以记录样式传递给方法的参数。
装饰器将方法输出调整为api样式:id，对于传统样式，id或False，对于记录样式，记录集:

@model
@returns('res.partner')
def find_partner(self, arg):
    ...     # 返回一些记录

# 输出取决于调用样式:传统的vs记录样式
partner_id = model.find_partner(cr, uid, arg, context=context)

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

注意，修饰后的方法必须满足该约定。
这些装饰器是自动继承的:覆盖已修饰的现有方法的方法将使用相同的@returns(model)来修饰。

openerp.api.one(method)

装饰一个记录样式的方法，其中self应该是一个单例实例。修饰后的方法会自动循环记录，并生成一个包含结果的列表。如果方法使用returns()修饰，则它将连接结果实例。这样一个方法:

@api.one
def method(self, args):
    return self.name

可以在记录和传统风格中调用，如:

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

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

自9.0版本起已弃用:
one()经常使代码不那么清晰，并且以开发人员和读者可能不期望的方式运行。
强烈建议使用multi()，并在self记录集上进行迭代，或者确保记录集是带有ensure_one()的单个记录。

openerp.api.v7(method_v7)

修饰一个只支持老式api的方法。可以通过重新定义同名的方法并使用v8()来提供一种新型的api:

@api.v7
def foo(self, cr, uid, ids, context=None):
    ...

@api.v8
def foo(self):
    ...

如果一个方法调用另一个方法，必须特别小心，因为该方法可能会被覆盖!在这种情况下，应该从当前类(比如MyClass)调用方法，例如:

@api.v7
def foo(self, cr, uid, ids, context=None):
    # 注意:record .foo()可能调用foo()的覆盖
    records = self.browse(cr, uid, ids, context)
    return MyClass.foo(records)

注意，包装器方法使用第一个方法的docstring。

openerp.api.v8(method_v8)

修饰一个只支持新风格api的方法。通过重新定义具有相同名称并使用v7()修饰的方法，可以提供旧式api:

@api.v8
def foo(self):
    ...

@api.v7
def foo(self, cr, uid, ids, context=None):
    ...

注意，包装器方法使用第一个方法的docstring。