doc/reference/orm.rst

   1 .. _reference/orm:
   2
   3 ===
   4 ORM
   5 ===
   6
   7 .. _reference/orm/model:
   8
   9 Model
  10 =====
  11
  12 .. - can't get autoattribute to import docstrings, so use regular attribute
  13    - no autoclassmethod
  14
  15 .. currentmodule:: openerp.models
  16
  17 .. autoclass:: openerp.models.Model
  18
  19     .. rubric:: Structural attributes
  20
  21     .. attribute:: _name
  22
  23         business object name, in dot-notation (in module namespace)
  24
  25     .. attribute:: _rec_name
  26
  27         Alternative field to use as name, used by osv’s name_get()
  28         (default: ``'name'``)
  29
  30     .. attribute:: _inherit
  31
  32         * If :attr:`._name` is set, names of parent models to inherit from.
  33           Can be a ``str`` if inheriting from a single parent
  34         * If :attr:`._name` is unset, name of a single model to extend
  35           in-place
  36
  37         See :ref:`reference/orm/inheritance`.
  38
  39     .. attribute:: _order
  40
  41         Ordering field when searching without an ordering specified (default:
  42         ``'id'``)
  43
  44         :type: str
  45
  46     .. attribute:: _auto
  47
  48         Whether a database table should be created (default: ``True``)
  49
  50         If set to ``False``, override :meth:`.init` to create the database
  51         table
  52
  53     .. attribute:: _table
  54
  55         Name of the table backing the model created when
  56         :attr:`~openerp.models.Model._auto`, automatically generated by
  57         default.
  58
  59     .. attribute:: _inherits
  60
  61         dictionary mapping the _name of the parent business objects to the
  62         names of the corresponding foreign key fields to use::
  63
  64             _inherits = {
  65                 'a.model': 'a_field_id',
  66                 'b.model': 'b_field_id'
  67             }
  68
  69         implements composition-based inheritance: the new model exposes all
  70         the fields of the :attr:`~openerp.models.Model._inherits`-ed model but
  71         stores none of them: the values themselves remain stored on the linked
  72         record.
  73
  74         .. warning::
  75
  76             if the same field is defined on multiple
  77             :attr:`~openerp.models.Model._inherits`-ed
  78
  79     .. attribute:: _constraints
  80
  81         list of ``(constraint_function, message, fields)`` defining Python
  82         constraints. The fields list is indicative
  83
  84         .. deprecated:: 8.0
  85
  86             use :func:`~openerp.api.constrains`
  87
  88     .. attribute:: _sql_constraints
  89
  90         list of ``(name, sql_definition, message)`` triples defining SQL
  91         constraints to execute when generating the backing table
  92
  93     .. attribute:: _parent_store
  94
  95         Alongside :attr:`~.parent_left` and :attr:`~.parent_right`, sets up a
  96         `nested set <http://en.wikipedia.org/wiki/Nested_set_model>`_  to
  97         enable fast hierarchical queries on the records of the current model
  98         (default: ``False``)
  99
 100         :type: bool
 101
 102     .. rubric:: CRUD
 103
 104     .. automethod:: create
 105     .. automethod:: browse
 106     .. automethod:: unlink
 107     .. automethod:: write
 108
 109     .. automethod:: read
 110
 111     .. rubric:: Research
 112
 113     .. automethod:: search
 114     .. automethod:: search_count
 115     .. automethod:: name_search
 116
 117     .. rubric:: Recordset operations
 118
 119     .. autoattribute:: ids
 120     .. automethod:: ensure_one
 121     .. automethod:: exists
 122     .. automethod:: filtered
 123     .. automethod:: sorted
 124     .. automethod:: update
 125
 126     .. rubric:: Environment swapping
 127
 128     .. automethod:: sudo
 129     .. automethod:: with_context
 130     .. automethod:: with_env
 131
 132     .. rubric:: Fields and views querying
 133
 134     .. automethod:: fields_get
 135     .. automethod:: fields_view_get
 136
 137     .. rubric:: ???
 138
 139     .. automethod:: default_get
 140     .. automethod:: copy
 141     .. automethod:: name_get
 142     .. automethod:: name_create
 143
 144     .. _reference/orm/model/automatic:
 145
 146     .. rubric:: Automatic fields
 147
 148     .. attribute:: id
 149
 150         Identifier :class:`field <openerp.fields.Field>`
 151
 152     .. attribute:: _log_access
 153
 154         Whether log access fields (``create_date``, ``write_uid``, ...) should
 155         be generated (default: ``True``)
 156
 157     .. attribute:: create_date
 158
 159         Date at which the record was created
 160
 161         :type: :class:`~openerp.field.Datetime`
 162
 163     .. attribute:: create_uid
 164
 165         Relational field to the user who created the record
 166
 167         :type: ``res.users``
 168
 169     .. attribute:: write_date
 170
 171         Date at which the record was last modified
 172
 173         :type: :class:`~openerp.field.Datetime`
 174
 175     .. attribute:: write_uid
 176
 177         Relational field to the last user who modified the record
 178
 179         :type: ``res.users``
 180
 181     .. rubric:: Reserved field names
 182
 183     A few field names are reserved for pre-defined behaviors beyond that of
 184     automated fields. They should be defined on a model when the related
 185     behavior is desired:
 186
 187     .. attribute:: name
 188
 189         default value for :attr:`~._rec_name`, used to
 190         display records in context where a representative "naming" is
 191         necessary.
 192
 193         :type: :class:`~openerp.fields.Char`
 194
 195     .. attribute:: active
 196
 197         toggles the global visibility of the record, if ``active`` is set to
 198         ``False`` the record is invisible in most searches and listing
 199
 200         :type: :class:`~openerp.fields.Boolean`
 201
 202     .. attribute:: sequence
 203
 204         Alterable ordering criteria, allows drag-and-drop reordering of models
 205         in list views
 206
 207         :type: :class:`~openerp.fields.Integer`
 208
 209     .. attribute:: state
 210
 211         lifecycle stages of the object, used by the ``states`` attribute on
 212         :class:`fields <openerp.fields.Field>`
 213
 214         :type: :class:`~openerp.fields.Selection`
 215
 216     .. attribute:: parent_id
 217
 218         used to order records in a tree structure and enables the ``child_of``
 219         operator in domains
 220
 221         :type: :class:`~openerp.fields.Many2one`
 222
 223     .. attribute:: parent_left
 224
 225         used with :attr:`~._parent_store`, allows faster tree structure access
 226
 227     .. attribute:: parent_right
 228
 229         see :attr:`~.parent_left`
 230
 231 .. _reference/orm/decorators:
 232
 233 Method decorators
 234 =================
 235
 236 .. automodule:: openerp.api
 237     :members: one, multi, model, depends, constrains, onchange, returns
 238
 239 .. _reference/orm/fields:
 240
 241 Fields
 242 ======
 243
 244 .. _reference/orm/fields/basic:
 245
 246 Basic fields
 247 ------------
 248
 249 .. autodoc documents descriptors as attributes, even for the *definition* of
 250    descriptors. As a result automodule:: openerp.fields lists all the field
 251    classes as attributes without providing inheritance info or methods (though
 252    we don't document methods as they're not useful for "external" devs)
 253    (because we don't support pluggable field types) (or do we?)
 254
 255 .. autoclass:: openerp.fields.Field
 256
 257 .. autoclass:: openerp.fields.Char
 258     :show-inheritance:
 259
 260 .. autoclass:: openerp.fields.Boolean
 261     :show-inheritance:
 262
 263 .. autoclass:: openerp.fields.Integer
 264     :show-inheritance:
 265
 266 .. autoclass:: openerp.fields.Float
 267     :show-inheritance:
 268
 269 .. autoclass:: openerp.fields.Text
 270     :show-inheritance:
 271
 272 .. autoclass:: openerp.fields.Selection
 273     :show-inheritance:
 274
 275 .. autoclass:: openerp.fields.Html
 276     :show-inheritance:
 277
 278 .. autoclass:: openerp.fields.Date
 279     :show-inheritance:
 280     :members: today, context_today, from_string, to_string
 281
 282 .. autoclass:: openerp.fields.Datetime
 283     :show-inheritance:
 284     :members: now, context_timestamp, from_string, to_string
 285
 286 .. _reference/orm/fields/relational:
 287
 288 Relational fields
 289 -----------------
 290
 291 .. autoclass:: openerp.fields.Many2one
 292     :show-inheritance:
 293
 294 .. autoclass:: openerp.fields.One2many
 295     :show-inheritance:
 296
 297 .. autoclass:: openerp.fields.Many2many
 298     :show-inheritance:
 299
 300 .. autoclass:: openerp.fields.Reference
 301     :show-inheritance:
 302
 303 .. _reference/orm/inheritance:
 304
 305 Inheritance and extension
 306 =========================
 307
 308 Odoo provides three different mechanisms to extend models in a modular way:
 309
 310 * creating a new model from an existing one, adding new information to the
 311   copy but leaving the original module as-is
 312 * extending models defined in other modules in-place, replacing the previous
 313   version
 314 * delegating some of the model's fields to records it contains
 315
 316 .. image:: ../images/inheritance_methods.png
 317     :align: center
 318
 319 Classical inheritance
 320 ---------------------
 321
 322 When using the :attr:`~openerp.models.Model._inherit` and
 323 :attr:`~openerp.models.Model._name` attributes together, Odoo creates a new
 324 model using the existing one (provided via
 325 :attr:`~openerp.models.Model._inherit`) as a base. The new model gets all the
 326 fields, methods and meta-information (defaults & al) from its base.
 327
 328 .. literalinclude:: ../../openerp/addons/test_documentation_examples/inheritance.py
 329     :language: python
 330     :lines: 5-
 331
 332 and using them:
 333
 334 .. literalinclude:: ../../openerp/addons/test_documentation_examples/tests/test_inheritance.py
 335     :language: python
 336     :lines: 8,12,9,19
 337
 338 will yield:
 339
 340 .. literalinclude:: ../../openerp/addons/test_documentation_examples/tests/test_inheritance.py
 341     :language: text
 342     :lines: 15,22
 343
 344 the second model has inherited from the first model's ``check`` method and its
 345 ``name`` field, but overridden the ``call`` method, as when using standard
 346 :ref:`Python inheritance <python:tut-inheritance>`.
 347
 348 Extension
 349 ---------
 350
 351 When using :attr:`~openerp.models.Model._inherit` but leaving out
 352 :attr:`~openerp.models.Model._name`, the new model replaces the existing one,
 353 essentially extending it in-place. This is useful to add new fields or methods
 354 to existing models (created in other modules), or to customize or reconfigure
 355 them (e.g. to change their default sort order):
 356
 357 .. literalinclude:: ../../openerp/addons/test_documentation_examples/extension.py
 358     :language: python
 359     :lines: 5-
 360
 361 .. literalinclude:: ../../openerp/addons/test_documentation_examples/tests/test_extension.py
 362     :language: python
 363     :lines: 8,13
 364
 365 will yield:
 366
 367 .. literalinclude:: ../../openerp/addons/test_documentation_examples/tests/test_extension.py
 368     :language: text
 369     :lines: 11
 370
 371 .. note:: it will also yield the various :ref:`automatic fields
 372           <reference/orm/model/automatic>` unless they've been disabled
 373
 374 Delegation
 375 ----------
 376
 377 The third inheritance mechanism provides more flexibility (it can be altered
 378 at runtime) but less power: using the :attr:`~openerp.models.Model._inherits`
 379 a model *delegates* the lookup of any field not found on the current model
 380 to "children" models. The delegation is performed via
 381 :class:`~openerp.fields.Reference` fields automatically set up on the parent
 382 model:
 383
 384 .. literalinclude:: ../../openerp/addons/test_documentation_examples/delegation.py
 385     :language: python
 386     :lines: 5-
 387
 388 .. literalinclude:: ../../openerp/addons/test_documentation_examples/tests/test_delegation.py
 389     :language: python
 390     :lines: 9-12,21,26
 391
 392 will result in:
 393
 394 .. literalinclude:: ../../openerp/addons/test_documentation_examples/tests/test_delegation.py
 395     :language: text
 396     :lines: 23,28
 397
 398 and it's possible to write directly on the delegated field:
 399
 400 .. literalinclude:: ../../openerp/addons/test_documentation_examples/tests/test_delegation.py
 401     :language: python
 402     :lines: 47
 403
 404 .. warning:: when using delegation inheritance, methods are *not* inherited,
 405              only fields
 406
 407 .. _reference/orm/domains:
 408
 409 Domains
 410 =======
 411
 412 A domain is a list of criteria, each criterion being a triple (either a
 413 ``list`` or a ``tuple``) of ``(field_name, operator, value)`` where:
 414
 415 ``field_name`` (``str``)
 416     a field name of the current model, or a relationship traversal through
 417     a :class:`~openerp.fields.Many2one` using dot-notation e.g. ``'street'``
 418     or ``'partner_id.country'``
 419 ``operator`` (``str``)
 420     an operator used to compare the ``field_name`` with the ``value``. Valid
 421     operators are:
 422
 423     ``=``
 424         equals to
 425     ``!=``
 426         not equals to
 427     ``>``
 428         greater than
 429     ``>=``
 430         greater than or equal to
 431     ``<``
 432         less than
 433     ``<=``
 434         less than or equal to
 435     ``=?``
 436         unset or equals to (returns true if ``value`` is either ``None`` or
 437         ``False``, otherwise behaves like ``=``)
 438     ``=like``
 439         matches ``field_name`` against the ``value`` pattern. An underscore
 440         ``_`` in the pattern stands for (matches) any single character; a
 441         percent sign ``%`` matches any string of zero or more characters.
 442     ``like``
 443         matches ``field_name`` against the ``%value%`` pattern. Similar to
 444         ``=like`` but wraps ``value`` with '%' before matching
 445     ``not like``
 446         doesn't match against the ``%value%`` pattern
 447     ``ilike``
 448         case insensitive ``like``
 449     ``not ilike``
 450         case insensitive ``not like``
 451     ``=ilike``
 452         case insensitive ``=like``
 453     ``in``
 454         is equal to any of the items from ``value``, ``value`` should be a
 455         list of items
 456     ``not in``
 457         is unequal to all of the items from ``value``
 458     ``child_of``
 459         is a child (descendant) of a ``value`` record.
 460
 461         Takes the semantics of the model into account (i.e following the
 462         relationship field named by
 463         :attr:`~openerp.models.Model._parent_name`).
 464
 465 ``value``
 466     variable type, must be comparable (through ``operator``) to the named
 467     field
 468
 469 Domain criteria can be combined using logical operators in *prefix* form:
 470
 471 ``'&'``
 472     logical *AND*, default operation to combine criteria following one
 473     another. Arity 2 (uses the next 2 criteria or combinations).
 474 ``'|'``
 475     logical *OR*, arity 2.
 476 ``'!'``
 477     logical *NOT*, arity 1.
 478
 479     .. tip:: Mostly to negate combinations of criteria
 480         :class: aphorism
 481
 482         Individual criterion generally have a negative form (e.g. ``=`` ->
 483         ``!=``, ``<`` -> ``>=``) which is simpler than negating the positive.
 484
 485 .. admonition:: Example
 486
 487     To search for partners named *ABC*, from belgium or germany, whose language
 488     is not english::
 489
 490         [('name','=','ABC'),
 491          ('language.code','!=','en_US'),
 492          '|',('country_id.code','=','be'),
 493              ('country_id.code','=','de')]
 494
 495     This domain is interpreted as:
 496
 497     .. code-block:: text
 498
 499             (name is 'ABC')
 500         AND (language is NOT english)
 501         AND (country is Belgium OR Germany)
 502