doc/new_api.rst

   1 ==================
   2 High-level ORM API
   3 ==================
   4
   5 .. _compute:
   6
   7 Computed fields: defaults and function fields
   8 =============================================
   9
  10 The high-level API attempts to unify concepts of programmatic value generation
  11 for function fields (stored or not) and default values through the use of
  12 computed fields.
  13
  14 Fields are marked as computed by setting their ``compute`` attribute to the
  15 name of the method used to compute then::
  16
  17     has_sibling = fields.Integer(compute='compute_has_sibling')
  18
  19 by default computation methods behave as simple defaults in case no
  20 corresponding value is found in the database::
  21
  22     def default_number_of_employees(self):
  23         self.number_of_employees = 1
  24
  25 .. todo::
  26
  27     literal defaults::
  28
  29         has_sibling = fields.Integer(compute=fields.default(1))
  30
  31 but they can also be used for computed fields by specifying fields used for
  32 the computation. The dependencies can be dotted for "cascading" through
  33 related models::
  34
  35     @api.depends('parent_id.children_count')
  36     def compute_has_sibling(self):
  37         self.has_sibling = self.parent_id.children_count >= 2
  38
  39 .. todo::
  40
  41     function-based::
  42
  43         has_sibling = fields.Integer()
  44         @has_sibling.computer
  45         @api.depends('parent_id.children_count')
  46         def compute_has_sibling(self):
  47             self.has_sibling = self.parent_id.children_count >= 2
  48
  49 note that computation methods (defaults or others) do not *return* a value,
  50 they *set*  values the current object. This means the high-level API does not
  51 need :ref:`an explicit multi <fields-functional>`: a ``multi`` method is
  52 simply one which computes several values at once::
  53
  54     @api.depends('company_id')
  55     def compute_relations(self):
  56         self.computed_company = self.company_id
  57         self.computed_companies = self.company_id.to_recordset()
  58
  59 Automatic onchange
  60 ==================
  61
  62 Using to the improved and expanded :ref:`computed fields <compute>`, the
  63 high-level ORM API is able to infer the effect of fields on
  64 one another, and thus automatically provide a basic form of onchange without
  65 having to implement it by hand, or implement dozens of onchange functions to
  66 get everything right.
  67
  68
  69
  70
  71 .. todo::
  72
  73     deferred records::
  74
  75         partner = Partner.record(42, defer=True)
  76         partner.name = "foo"
  77         partner.user_id = juan
  78         partner.save() # only saved to db here
  79
  80         with scope.defer():
  81             # all records in this scope or children scopes are deferred
  82             #   until corresponding scope poped or until *this* scope poped?
  83             partner = Partner.record(42)
  84             partner.name = "foo"
  85             partner.user_id = juan
  86         # saved here, also for recordset &al, ~transaction
  87
  88         # temp deferment, maybe simpler? Or for bulk operations?:
  89         with Partner.record(42) as partner:
  90             partner.name = "foo"
  91             partner.user_id = juan
  92
  93     ``id = False`` => always defered? null v draft?
  94
  95 .. todo:: keyword arguments passed positionally (common for context, completely breaks everything)
  96
  97 .. todo:: optional arguments (report_aged_receivable)
  98
  99 .. todo:: non-id ids? (mail thread_id)
 100
 101 .. todo:: partial signatures on overrides (e.g. message_post)
 102
 103 .. todo::
 104
 105     ::
 106
 107         field = fields.Char()
 108
 109         @field.computer
 110         def foo(self):
 111             "compute foo here"
 112
 113     ~
 114
 115     ::
 116
 117         field = fields.Char(compute='foo')
 118
 119         def foo(self):
 120             "compute foo here"
 121
 122 .. todo:: doc
 123
 124 .. todo:: incorrect dependency spec?
 125
 126 .. todo:: dynamic dependencies?
 127
 128     ::
 129
 130         @api.depends(???)
 131         def foo(self)
 132             self.a = self[self.b]
 133
 134 .. todo:: recursive onchange
 135
 136     Country & state. Change country -> remove state; set state -> set country
 137
 138 .. todo:: onchange list affected?