.. _reference/orm:

===
ORM
===

.. _reference/orm/model:

Model
=====

.. - can't get autoattribute to import docstrings, so use regular attribute
   - no autoclassmethod

.. currentmodule:: openerp.models

.. autoclass:: openerp.models.Model

    .. rubric:: Structural attributes

    .. attribute:: _name

        business object name, in dot-notation (in module namespace)

    .. attribute:: _rec_name

        Alternative field to use as name, used by osv’s name_get()
        (default: ``'name'``)

    .. attribute:: _inherit

        * If :attr:`._name` is set, names of parent models to inherit from.
          Can be a ``str`` if inheriting from a single parent
        * If :attr:`._name` is unset, name of a single model to extend
          in-place

    .. attribute:: _order

        Ordering field when searching without an ordering specified (default:
        ``'id'``)

        :type: str

    .. attribute:: _auto

        Whether a database table should be created (default: ``True``)

        If set to ``False``, override :meth:`.init` to create the database
        table

    .. attribute:: _table

        Name of the table backing the model created when
        :attr:`~openerp.models.Model._auto`, automatically generated by
        default.

    .. attribute:: _inherits

        dictionary mapping the _name of the parent business objects to the
        names of the corresponding foreign key fields to use::

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

        implements composition-based inheritance: the new model exposes all
        the fields of the :attr:`~openerp.models.Model._inherits`-ed model but
        stores none of them: the values themselves remain stored on the linked
        record.

        .. warning::

            if the same field is defined on multiple
            :attr:`~openerp.models.Model._inherits`-ed

    .. attribute:: _constraints

        list of ``(constraint_function, message, fields)`` defining Python
        constraints. The fields list is indicative

        .. deprecated:: 8.0

            use :func:`~openerp.api.constrains`

    .. attribute:: _sql_constraints

        list of ``(name, sql_definition, message)`` triples defining SQL
        constraints to execute when generating the backing table

    .. attribute:: _parent_store

        Alongside :attr:`~.parent_left` and :attr:`~.parent_right`, sets up a
        `nested set <http://en.wikipedia.org/wiki/Nested_set_model>`_  to
        enable fast hierarchical queries on the records of the current model
        (default: ``False``)

        :type: bool

    .. rubric:: CRUD

    .. automethod:: create
    .. automethod:: browse
    .. automethod:: unlink
    .. automethod:: write

    .. automethod:: read

    .. rubric:: Research

    .. automethod:: search
    .. automethod:: search_count
    .. automethod:: name_search

    .. rubric:: Recordset operations

    .. autoattribute:: ids
    .. automethod:: ensure_one
    .. automethod:: exists
    .. automethod:: filtered
    .. automethod:: sorted
    .. automethod:: update

    .. rubric:: Environment swapping

    .. automethod:: sudo
    .. automethod:: with_context
    .. automethod:: with_env

    .. rubric:: Fields and views querying

    .. automethod:: fields_get
    .. automethod:: fields_view_get

    .. rubric:: ???

    .. automethod:: default_get
    .. automethod:: copy
    .. automethod:: add_default_value
    .. automethod:: name_get
    .. automethod:: name_create

    .. rubric:: Automatic fields

    .. attribute:: id

        Identifier :class:`field <openerp.fields.Field>`

    .. attribute:: _log_access

        Whether log access fields (``create_date``, ``write_uid``, ...) should
        be generated (default: ``True``)

    .. attribute:: create_date

        Date at which the record was created

        :type: :class:`~openerp.field.Datetime`

    .. attribute:: create_uid

        Relational field to the user who created the record

        :type: ``res.users``

    .. attribute:: write_date

        Date at which the record was last modified

        :type: :class:`~openerp.field.Datetime`

    .. attribute:: write_uid

        Relational field to the last user who modified the record

        :type: ``res.users``

    .. rubric:: Reserved field names

    A few field names are reserved for pre-defined behaviors beyond that of
    automated fields. They should be defined on a model when the related
    behavior is desired:

    .. attribute:: name

        default value for :attr:`~._rec_name`, used to
        display records in context where a representative "naming" is
        necessary.

        :type: :class:`~openerp.fields.Char`

    .. attribute:: active

        toggles the global visibility of the record, if ``active`` is set to
        ``False`` the record is invisible in most searches and listing

        :type: :class:`~openerp.fields.Boolean`

    .. attribute:: sequence

        Alterable ordering criteria, allows drag-and-drop reordering of models
        in list views

        :type: :class:`~openerp.fields.Integer`

    .. attribute:: state

        lifecycle stages of the object, used by the ``states`` attribute on
        :class:`fields <openerp.fields.Field>`

        :type: :class:`~openerp.fields.Selection`

    .. attribute:: parent_id

        used to order records in a tree structure and enables the ``child_of``
        operator in domains

        :type: :class:`~openerp.fields.Many2one`

    .. attribute:: parent_left

        used with :attr:`~._parent_store`, allows faster tree structure access

    .. attribute:: parent_right

        see :attr:`~.parent_left`

.. _reference/orm/decorators:

Method decorators
=================

.. automodule:: openerp.api
    :members: one, multi, model, depends, constrains, onchange, returns

.. _reference/orm/fields:

Fields
======

.. _reference/orm/fields/basic:

Basic fields
------------

.. autodoc documents descriptors as attributes, even for the *definition* of
   descriptors. As a result automodule:: openerp.fields lists all the field
   classes as attributes without providing inheritance info or methods (though
   we don't document methods as they're not useful for "external" devs)
   (because we don't support pluggable field types) (or do we?)

.. autoclass:: openerp.fields.Field

.. autoclass:: openerp.fields.Char
    :show-inheritance:

.. autoclass:: openerp.fields.Boolean
    :show-inheritance:

.. autoclass:: openerp.fields.Integer
    :show-inheritance:

.. autoclass:: openerp.fields.Float
    :show-inheritance:

.. autoclass:: openerp.fields.Text
    :show-inheritance:

.. autoclass:: openerp.fields.Selection
    :show-inheritance:

.. autoclass:: openerp.fields.Html
    :show-inheritance:

.. autoclass:: openerp.fields.Date
    :show-inheritance:
    :members: today, context_today, from_string, to_string

.. autoclass:: openerp.fields.Datetime
    :show-inheritance:
    :members: now, context_timestamp, from_string, to_string

.. _reference/orm/fields/relational:

Relational fields
-----------------

.. autoclass:: openerp.fields.Many2one
    :show-inheritance:

.. autoclass:: openerp.fields.One2many
    :show-inheritance:

.. autoclass:: openerp.fields.Many2many
    :show-inheritance:

.. autoclass:: openerp.fields.Reference
    :show-inheritance:

.. _reference/orm/domains:

Domains
=======

A domain is a list of criterion, each criterion being a triple (either a
``list`` or a ``tuple``) of ``(field_name, operator, value)`` where:

``field_name`` (``str``)
    a field name of the current model, or a relationship traversal through
    a :class:`~openerp.fields.Many2one` using dot-notation e.g. ``'street'``
    or ``'partner_id.country'``
``operator`` (``str``)
    a comparison operator between the criterion's field and value.

    .. todo:: list and detail operators, original list is way incomplete
``value``
    variable type, must be comparable (through ``operator``) to the named
    field

Domain criteria can be combined using logical operators in *prefix* form:

``'&'``
    logical *AND*, default operation to combine criteria following one
    another. Arity 2 (uses the next 2 criteria or combinations).
``'|'``
    logical *OR*, arity 2.
``'!'``
    logical *NOT*, arity 1.

    .. tip:: Mostly to negate combinations of criteria
        :class: aphorism

        Individual criterion generally have a negative form (e.g. ``=`` ->
        ``!=``, ``<`` -> ``>=``) which is simpler than negating the positive.

.. admonition:: Example

    To search for partners named *ABC*, from belgium or germany, whose language
    is not english::

        [('name','=','ABC'),
         ('language.code','!=','en_US'),
         '|',('country_id.code','=','be'),
             ('country_id.code','=','de')]

    This domain is interpreted as:

    .. code-block:: text

            (name is 'ABC')
        AND (language is NOT english)
        AND (country is Belgium OR Germany)