Coverage for adhoc-cicd-odoo-odoo / odoo / orm / decorators.py: 88%
74 statements
« prev ^ index » next coverage.py v7.13.4, created at 2026-03-09 18:05 +0000
1# Part of Odoo. See LICENSE file for full copyright and licensing details.
3"""The Odoo API module defines method decorators.
4"""
5from __future__ import annotations
7import logging
8import typing
9import warnings
10from collections.abc import Mapping
11from functools import wraps
13try:
14 # available since python 3.13
15 from warnings import deprecated
16except ImportError:
17 # simplified version
18 class deprecated:
19 def __init__(
20 self,
21 message: str,
22 /,
23 *,
24 category: type[Warning] | None = DeprecationWarning,
25 stacklevel: int = 1,
26 ) -> None:
27 self.message = message
28 self.category = category
29 self.stacklevel = stacklevel
31 def __call__(self, obj, /):
32 message = self.message
33 category = self.category
34 stacklevel = self.stacklevel
35 if category is None: 35 ↛ 36line 35 didn't jump to line 36 because the condition on line 35 was never true
36 obj.__deprecated__ = message
37 return obj
38 if callable(obj): 38 ↛ 46line 38 didn't jump to line 46 because the condition on line 38 was always true
39 @wraps(obj)
40 def wrapper(*args, **kwargs):
41 warnings.warn(message, category=category, stacklevel=stacklevel + 1)
42 return obj(*args, **kwargs)
44 obj.__deprecated__ = wrapper.__deprecated__ = message
45 return wrapper
46 raise TypeError(f"@deprecated decorator cannot be applied to {obj!r}")
48if typing.TYPE_CHECKING:
49 from collections.abc import Callable, Collection
50 from .types import BaseModel, ValuesType
52 T = typing.TypeVar('T')
53 C = typing.TypeVar("C", bound=Callable)
54 Decorator = Callable[[C], C]
56_logger = logging.getLogger('odoo.api')
59# The following attributes are used, and reflected on wrapping methods:
60# - method._constrains: set by @constrains, specifies constraint dependencies
61# - method._depends: set by @depends, specifies compute dependencies
62# - method._onchange: set by @onchange, specifies onchange fields
63# - method._ondelete: set by @ondelete, used to raise errors for unlink operations
64#
65# On wrapping method only:
66# - method._api_*: decorator function, used for re-applying decorator
67#
69def attrsetter(attr, value) -> Decorator:
70 """ Return a function that sets ``attr`` on its argument and returns it. """
71 def setter(method):
72 setattr(method, attr, value)
73 return method
75 return setter
78@typing.overload
79def constrains(func: Callable[[BaseModel], Collection[str]], /) -> Decorator:
80 ...
83@typing.overload
84def constrains(*args: str) -> Decorator:
85 ...
88def constrains(*args) -> Decorator:
89 """Decorate a constraint checker.
91 Each argument must be a field name used in the check::
93 @api.constrains('name', 'description')
94 def _check_description(self):
95 for record in self:
96 if record.name == record.description:
97 raise ValidationError("Fields name and description must be different")
99 Invoked on the records on which one of the named fields has been modified.
101 Should raise :exc:`~odoo.exceptions.ValidationError` if the
102 validation failed.
104 .. warning::
106 ``@constrains`` only supports simple field names, dotted names
107 (fields of relational fields e.g. ``partner_id.customer``) are not
108 supported and will be ignored.
110 ``@constrains`` will be triggered only if the declared fields in the
111 decorated method are included in the ``create`` or ``write`` call.
112 It implies that fields not present in a view will not trigger a call
113 during a record creation. A override of ``create`` is necessary to make
114 sure a constraint will always be triggered (e.g. to test the absence of
115 value).
117 One may also pass a single function as argument. In that case, the field
118 names are given by calling the function with a model instance.
120 """
121 if args and callable(args[0]):
122 args = args[0]
123 return attrsetter('_constrains', args)
126def ondelete(*, at_uninstall: bool) -> Decorator:
127 """
128 Mark a method to be executed during :meth:`~odoo.models.BaseModel.unlink`.
130 The goal of this decorator is to allow client-side errors when unlinking
131 records if, from a business point of view, it does not make sense to delete
132 such records. For instance, a user should not be able to delete a validated
133 sales order.
135 While this could be implemented by simply overriding the method ``unlink``
136 on the model, it has the drawback of not being compatible with module
137 uninstallation. When uninstalling the module, the override could raise user
138 errors, but we shouldn't care because the module is being uninstalled, and
139 thus **all** records related to the module should be removed anyway.
141 This means that by overriding ``unlink``, there is a big chance that some
142 tables/records may remain as leftover data from the uninstalled module. This
143 leaves the database in an inconsistent state. Moreover, there is a risk of
144 conflicts if the module is ever reinstalled on that database.
146 Methods decorated with ``@ondelete`` should raise an error following some
147 conditions, and by convention, the method should be named either
148 ``_unlink_if_<condition>`` or ``_unlink_except_<not_condition>``.
150 .. code-block:: python
152 @api.ondelete(at_uninstall=False)
153 def _unlink_if_user_inactive(self):
154 if any(user.active for user in self):
155 raise UserError("Can't delete an active user!")
157 # same as above but with _unlink_except_* as method name
158 @api.ondelete(at_uninstall=False)
159 def _unlink_except_active_user(self):
160 if any(user.active for user in self):
161 raise UserError("Can't delete an active user!")
163 :param bool at_uninstall: Whether the decorated method should be called if
164 the module that implements said method is being uninstalled. Should
165 almost always be ``False``, so that module uninstallation does not
166 trigger those errors.
168 .. danger::
169 The parameter ``at_uninstall`` should only be set to ``True`` if the
170 check you are implementing also applies when uninstalling the module.
172 For instance, it doesn't matter if when uninstalling ``sale``, validated
173 sales orders are being deleted because all data pertaining to ``sale``
174 should be deleted anyway, in that case ``at_uninstall`` should be set to
175 ``False``.
177 However, it makes sense to prevent the removal of the default language
178 if no other languages are installed, since deleting the default language
179 will break a lot of basic behavior. In this case, ``at_uninstall``
180 should be set to ``True``.
181 """
182 return attrsetter('_ondelete', at_uninstall)
185def onchange(*args: str) -> Decorator:
186 """Return a decorator to decorate an onchange method for given fields.
188 In the form views where the field appears, the method will be called
189 when one of the given fields is modified. The method is invoked on a
190 pseudo-record that contains the values present in the form. Field
191 assignments on that record are automatically sent back to the client.
193 Each argument must be a field name::
195 @api.onchange('partner_id')
196 def _onchange_partner(self):
197 self.message = "Dear %s" % (self.partner_id.name or "")
199 .. code-block:: python
201 return {
202 'warning': {'title': "Warning", 'message': "What is this?", 'type': 'notification'},
203 }
205 If the type is set to notification, the warning will be displayed in a notification.
206 Otherwise it will be displayed in a dialog as default.
208 .. warning::
210 ``@onchange`` only supports simple field names, dotted names
211 (fields of relational fields e.g. ``partner_id.tz``) are not
212 supported and will be ignored
214 .. danger::
216 Since ``@onchange`` returns a recordset of pseudo-records,
217 calling any one of the CRUD methods
218 (:meth:`create`, :meth:`read`, :meth:`write`, :meth:`unlink`)
219 on the aforementioned recordset is undefined behaviour,
220 as they potentially do not exist in the database yet.
222 Instead, simply set the record's field like shown in the example
223 above or call the :meth:`update` method.
225 .. warning::
227 It is not possible for a ``one2many`` or ``many2many`` field to modify
228 itself via onchange. This is a webclient limitation - see `#2693 <https://github.com/odoo/odoo/issues/2693>`_.
230 """
231 return attrsetter('_onchange', args)
234@typing.overload
235def depends(func: Callable[[BaseModel], Collection[str]], /) -> Decorator:
236 ...
239@typing.overload
240def depends(*args: str) -> Decorator:
241 ...
244def depends(*args) -> Decorator:
245 """ Return a decorator that specifies the field dependencies of a "compute"
246 method (for new-style function fields). Each argument must be a string
247 that consists in a dot-separated sequence of field names::
249 pname = fields.Char(compute='_compute_pname')
251 @api.depends('partner_id.name', 'partner_id.is_company')
252 def _compute_pname(self):
253 for record in self:
254 if record.partner_id.is_company:
255 record.pname = (record.partner_id.name or "").upper()
256 else:
257 record.pname = record.partner_id.name
259 One may also pass a single function as argument. In that case, the
260 dependencies are given by calling the function with the field's model.
261 """
262 if args and callable(args[0]):
263 args = args[0]
264 elif any('id' in arg.split('.') for arg in args): 264 ↛ 265line 264 didn't jump to line 265 because the condition on line 264 was never true
265 raise NotImplementedError("Compute method cannot depend on field 'id'.")
266 return attrsetter('_depends', args)
269def depends_context(*args: str) -> Decorator:
270 """ Return a decorator that specifies the context dependencies of a
271 non-stored "compute" method. Each argument is a key in the context's
272 dictionary::
274 price = fields.Float(compute='_compute_product_price')
276 @api.depends_context('pricelist')
277 def _compute_product_price(self):
278 for product in self:
279 if product.env.context.get('pricelist'):
280 pricelist = self.env['product.pricelist'].browse(product.env.context['pricelist'])
281 else:
282 pricelist = self.env['product.pricelist'].get_default_pricelist()
283 product.price = pricelist._get_products_price(product).get(product.id, 0.0)
285 All dependencies must be hashable. The following keys have special
286 support:
288 * `company` (value in context or current company id),
289 * `uid` (current user id and superuser flag),
290 * `active_test` (value in env.context or value in field.context).
291 """
292 return attrsetter('_depends_context', args)
295def autovacuum(method: C) -> C:
296 """
297 Decorate a method so that it is called by the daily vacuum cron job (model
298 ``ir.autovacuum``). This is typically used for garbage-collection-like
299 tasks that do not deserve a specific cron job.
301 A return value can be a tuple (done, remaining) which have simular meaning
302 as in :meth:`~odoo.addons.base.models.ir_cron.IrCron._commit_progress`.
303 """
304 assert method.__name__.startswith('_'), "%s: autovacuum methods must be private" % method.__name__
305 method._autovacuum = True # type: ignore
306 return method
309def model(method: C) -> C:
310 """ Decorate a record-style method where ``self`` is a recordset, but its
311 contents is not relevant, only the model is. Such a method::
313 @api.model
314 def method(self, args):
315 ...
317 """
318 if method.__name__ == 'create': 318 ↛ 319line 318 didn't jump to line 319 because the condition on line 318 was never true
319 return model_create_multi(method) # type: ignore
320 method._api_model = True # type: ignore
321 return method
324def private(method: C) -> C:
325 """ Decorate a record-style method to indicate that the method cannot be
326 called using RPC. Example::
328 @api.private
329 def method(self, args):
330 ...
332 If you have business methods that should not be called over RPC, you
333 should prefix them with "_". This decorator may be used in case of
334 existing public methods that become non-RPC callable or for ORM
335 methods.
336 """
337 method._api_private = True # type: ignore
338 return method
341def readonly(method: C) -> C:
342 """ Decorate a record-style method where ``self.env.cr`` can be a
343 readonly cursor when called trough a rpc call.
345 @api.readonly
346 def method(self, args):
347 ...
348 """
349 method._readonly = True # type: ignore
350 return method
353def model_create_multi(method: Callable[[T, list[ValuesType]], T]) -> Callable[[T, list[ValuesType] | ValuesType], T]:
354 """ Decorate a method that takes a list of dictionaries and creates multiple
355 records. The method may be called with either a single dict or a list of
356 dicts::
358 record = model.create(vals)
359 records = model.create([vals, ...])
360 """
361 @wraps(method)
362 def create(self: T, vals_list: list[ValuesType] | ValuesType) -> T:
363 if isinstance(vals_list, Mapping):
364 vals_list = [vals_list]
365 return method(self, vals_list)
367 create._api_model = True # type: ignore
368 return create