Odoo ORM API（三）- Model Reference

Model Reference

class openerp.models.Model(pool, cr)
OPENERP 的 Models 都是繼承自這個 class

class user(Model):
    ...

這個在每個數據庫中值會被系統實例化一次。

Structual attributes

• _name
  business object name， 通常是 ‘.’，用於存放在 module的命名空間中

• _rec_name
  可選的，用於將某個字段設置成name， 將被 osv 的 name_get()調用（默認爲 name）

• _inherit

  • 如果 _name 設置了，那麼它的值就是 他想繼承的的父類的 _name，如果只是繼承一個父類，可以直接設置成str，將會把數據存在自己的表上
  • 如果 _name 沒有設置，將會直接在父類的表上進行拓展修改。

• _order
  默認的order選項（default: ‘id’）, 如果search（）中設置了 order 參數，將以後者爲準

• _auto
  是否創建一個數據庫表（default：True），如果設置爲False，需要複寫 init（）用以創建數據表

• _table
  當創建數據表時，使用的名字，通常會根據默認參數自動生成

• _inherits
  傳入一個字典，key 是繼承的model的_name，值爲field的名字。

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

這個新的model，與父類相關的值都不會存在自己的表中，而是存儲在父類的表中。

• _constrains
  list of (constraint_function, message, field) ，8.0之後不再贊成使用，建議使用 api.constrains()

• _sql_constraints
  list of (name, sql_definition, message) triples , 當建立數據表時，用以限制。

• _parent_store
  Alongside parent_left and parent_right，設置一個 nested set 用以快速查詢當前model的record。（default: False）

CRUD （create，retrieve，update，delete）

• create(vals) -> record
  爲這個 model 創建一個新的 record。
  這個新的 record 使用提供的值來初始化，如果必要的話，從default_get() 取值

Name	描述
參數	vals(dict),{‘field_name’: field_value, …}
返回值	一個創建的新的record
報錯	AcessError: 如果當前user沒有創建這個object的權限，或者用戶試圖繞過訪問規則創建請求對象. ValidateError: 給selection字段傳入一個無效的值。 UserError: 如果創建了一個循環調用，如：給一個res.partner設置它自己爲自己的parent_id

• browse([ids]) -> records
  根據提供的ids，返回對應id的record組成的recordset
  可以不提供Id，或者只有一個Id，或者sequence of ids

• unlink()
  刪除當前的recordsets
  可能會拋出 AcessError（和write一樣） 或者 UserError（如果這個record是其它records的默認屬性）

• write(vals)
  把當前recordset中所有record根據提供的參數，修改值
  其餘基本和 create 一樣

  • 如果是數字類的 fields（Integer，Float），傳入的value也應該是對應的 type
  • Boolean field 的話，就應該傳入 boolean
  • Selection field，傳入對應的選項，多數是str，極少爲 integer
  • Many2one，應該傳入對應record的 database id

  • 其它的非關係型的字段，就傳入 str

    注意：
    由於歷史的兼容性的原因， Date 和 Datetime fields 讀寫中得到的都是 str 類型，而非對應的 date 和 datetime 類型。date string 都是 UTC-only 的，format 格式爲 "%Y-%m-%d" 和 "%Y-%m-%d %H:%M:%S"

  • One2many 和 Many2many 使用一個特殊的命令，還將這些record與這個字段關聯起來
    這個命令就是 由多個元祖（3個元素）組成的列表，每一個元祖都是一條命令，它們將按順序執行，通常是這些：

    1. (0, _, values) 給這個field 添加一個新的 record，這個新的record 是根據 values(dict)的值創建出來的。
    2. (1, id, values) 用values（dict）來更新這個 field 已經關聯到的 id 爲 傳入 id的 record， 不能用在 create()中
    3. (2, id, _) 將 id 爲傳入 id的record 從 field的關聯中刪除，並且將其從數據庫中刪除。不能用在create()中
    4. (3, id, _) 將 id 爲傳入 id的record 從 field的關聯中刪除，但是不從數據庫中刪除。不能作用在One2many字段上，也不能用在create()中
    5. (4, id, _) 將一個已經存在的id爲傳入id的record添加到field的關聯中，不能作用在One2many字段上，
    6. (5, _, _) 將這個field的關聯集清空，等同於對這個集合中的每一個record執行 (3, id, _) 命令。不能用在One2many，不用再create（）
    7. (6, _, ids) 用ids這些records來替代原有field對應的關聯集，等同於先對這個record執行(5, _, _)，再對ids中的每一個record，執行(4, id, _)。
       

    提示：
    上面 的 _ 都代表不重要的意思，通常填入 False 或者 0

• read([fields])
  讀取對應field的值，並將他們以字典的形式返回。每一個record一個字典，最後返回一個列表。

• read_group(*args, **kwargs)
  Get the list of records in list view grouped by the given groupby fields

Name	描述
參數	cr - database cursor uid - 當前用戶id domain - 普通的domain，表明在哪些符合要求的record進行read_group fields(list) - 列出需要展現的字段 groupby(list) - 列出根據哪些字段來分組，這中間要麼直接寫出字段名稱，或者field:groupby_function，groupby_function目前只支持day,week,month,quarter,year，並且只能作用於 Date 和 Datetime 類型的字段 offset(int) - 可選的，用以跳過幾條record limit(int) - 可選，只返回一定數目的record context(dict) - 基本的context參數，比如lang、time zone orderby(list)，就和search()中的orderby一樣，目前僅支持many2one lazy(bool) - 如果爲True，那麼就只groupby第一個groupby，其它的groupby傳入到__context key中。如果是False,一次性將所有的groupby全部執行
返回值	多個dict(每個record一個dict)組成的list,每個dict包含： 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
返回類型	[{‘field_name_1’: value, …]
異常	AcessError: 如果當前user沒有創建這個object的權限，或者用戶試圖繞過訪問規則創建請求對象.

Searching

• search(args[, offset=0][, limit=None][, order=None][, count=False])
  最主要的就是args中的domain

Name	描述
參數	args - 一個 search domain， 如果沒有domain，傳入一個空列表，表示所有 offset (int) 忽略多少個 limit（int） - 最大返回多少個 order（str），一個由field name組成的str，其中用逗號分隔 count（bool） - 如果設置爲True，僅僅用來計數符合要求的數目，並且返回這個數。默認是False
返回值	多數情況下，返回一個符合要求的recordset
報錯	AcessError: 如果當前user沒有創建這個object的權限，或者用戶試圖繞過訪問規則創建請求對象.

• search_count(args) -> int
  返回符合domain的record的數目

• name_search(name='', args=None, operator='ilike', limit=100) -> records
  將name符合pattern的record篩選出來，包含 domian（args）
  相當於進行search（）後，再name_get()

Name	描述
參數	name - 搜索的pattern args - 一個 search domain， 如果沒有domain，傳入一個空列表，表示所有 operator（str），ilike, =，等 limit（int） - 最大返回多少個
返回類型	list
返回值	符合要求的record的 list of pairs （Id，text_repr）

Recordset operations

• ids 返回這個recordset所有record的數據表id組成的list

• ensure_one() 驗證這個recordset的長度是否爲1，否則拋出異常

• exists() -> records ，返回這個recordset中所有實際存在的recordset。

• filtered(func)
  返回這個func(rec)爲True的所有record組成的recordset。這個func可以是一個函數，也可以是一個以點分隔的field names。

• sorted(key=None, reverse=False)
  返回根據key排序的recordset，key和普通python sorted 的 key 差不多

• mapped(func)
  將func作用於每一個record上，如果func返回recordset，那麼總體就返回recordset，否則總體返回list
  func可以是 函數，也可以是以點分隔的field names。

Enviroment swapping

• sudo([user=SUPERUSER])
  返回一個適用於傳入user的recordset
  默認情況下，返回一個superuser權限的recordset，這將會直接越過 access control 和 record rule。

  注意:
  由於使用 sudo 將會越過各種權限設置，所以查詢出來的數據可能會包含本來設置爲區分的record
  比如（多公司環境下的record）

  而且，這個新的recordset 將不會被cache。所以，查詢數據將會產生一定的延遲。

• with_context([context][, **overrides]) -> records
  返回一個新的符合給定context的recordset

# 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)
  返回一個新的符合給定env的recordset
  

注意：
這個新的environment將不會採用當期environment的cache，所以後續的數據查詢將會有延遲，因爲要直接從數據庫中讀取。

Fields and views querying

• fields_get([fields][, attributes])
  返回每個field的definition
  返回值是一個dict，傳入的field作爲key。同樣可以傳入_inherit的model的field，每一個field對應一個字典，其中string，help和selection都會被自動翻譯。
  Parameters
  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'])
  Get the detailed composition of the requested view like fields, model, view architecture
  Parameters
  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
  Returns dictionary describing the composition of the requested view (including inherited views and extensions)
  Raises
  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

???

• default_get(fields_list) -> default_values
  返回這個fields_list中所有field對應default value，這些default value由context，user default，和 models自己定義的決定。
  Parameters fields_list – a list of field names
  Returns 返回一個字典，fields_name : default value。如果這個field，有defualt value

• copy(default=None)
  複製當前record，並用default更新
  Parameters default (dict) – dictionary of field values to override in the original values of the copied record, e.g: {‘field_name’: overridden_value, …}
  Returns new record

• name_get() -> [(id, name), …]
  返回這個recordset中所有record對應的名字，默認是返回record的 display_name 字段。

  name	descrition
  Returns	list of pairs (id, text_repr) for each records
  Return type	list(tuple)

• name_create(name) -> record
  通過 create() 創建一個新的record，但是隻傳入一個參數（display_name）。
  這個新的record將採用一切合適的default Value，包括context中包含的。

  name	descrition
  Parameters	name – display name of the record to create
  Returns	the name_get() pair value of the created record
  Return type	record

Automatic fields

• id

• _log_access 默認爲True

• create_date 創建record的時間 type： datetime

• create_uid 創建record的用戶 type： res.users

• write_date 最近一次修改的時間 type：datetime

• write_uid 最近一次對其修改的用戶 type： res.users

Reserved field names

有些字段名字，是作爲保留字段，被預先定義好了。如果你要在某個model中實現這種相關的功能，可以通過定義這些名字的field來實現。

• name type Char
  _rec_name 字段的默認值，通常用來顯示一個record的可讀的名字

• active type Boolean
  用以全局的改變這個record的可見，如果active 被設置爲False，那麼絕大多數的search和listing中都不會顯示

• sequence type Integer
  修改order的標準，同時允許在tree view界面，進行拖曳，用以調整順序

• state type Selection
  一個object的週期，可以被用在field的states屬性中

• parent_id type Many2one
  設置各種層級，並且可以在domain中使用child_of operator

• parent_left
  和 _parent_store 一起使用，通常是爲了高效率的 tree structure

• parent_right
  同上