First snapshot of trytond documentation refactoring

doc/ref/models/fields.rst

 .. _ref-models-fields:
 .. module:: trytond.model.fields
 
 ======
 Fields
 ======
 
-Fields define the behaviors of the data on model's record.

[udono, 2010/05/07 12:48:31]

behavior

+Fields define the behavior of the data on model's record.
 
 Field options
 =============
 
 The following arguments are available to all field types. All are optional
 except :attr:`Field.string`.
 
 ``string``
 ----------
 
@@ skipping 23 matching lines @@
 If ``True``, the field is not editable in the client. Default is ``False``.
 
 ``domain``
 ----------
 
 .. attribute:: Field.domain
 
 A :ref:`domain <topics-domain>` constraint that will be applied on the field
 value.
 
 .. warning::

[udono, 2010/05/07 12:48:31]

.. note:: ?

 
     For now it only works on relational fields like :class:`Many2One`,
     :class:`One2Many` and :class:`Many2Many`.
 ..
 
 ``states``
 ----------
 
 .. attribute:: Field.states
 
 A dictionary that defines dynamic states of the field and overrides the static
 one. Possible keys are ``required``, ``readonly`` and ``invisible``.
 The values are :class:`~trytond.pyson.PYSON` statements that will be evaluated
-with the record values.

[udono, 2010/05/07 12:48:31]

with the values of the record.

+with the values of the record.
 
 ``priority``
 ------------
 
 .. attribute:: Field.priority
 
 Give the order in which setter methods (if exist) are called on a model.

[udono, 2010/05/07 12:48:31]

An integer, which give...
Default is 0. Lower priority called first.

+Default is 0. Lower priority called first.
 
 ``change_default``
 ------------------
 
 .. attribute:: Field.change_default
 
 If true, the field can be used as condition for a custom default value.
 
 ``select``
 ----------
 
 .. attribute:: Field.select
 
 When equal to ``1``, the field appears in the search box in list view and the
 search will be optimized. When equal to ``2`` the field appears in the
 *Advanced Search* in the search box.
 
 ``on_change``
 -------------
 
 .. attribute:: Field.on_change
 
-A list of field names, if this attribute is set, the client will call the

[udono, 2010/05/07 12:48:31]

... names. If ...

+A list of field names. If this attribute is set, the client will call the
 method ``on_change_<field name>`` of the model when the user changes the
 current field value and will give the values of each fields in this list. The
 method signature is::
 
     on_change_<field name>(cursor, user, values[, context])
 
-It must return a dictionary with the values of fields that must be updated.

[udono, 2010/05/07 12:48:31]

    This method need to return a dictionary with the values of fields to be
updated.

+This method must return a dictionary with the values of fields to be updated.
 
 .. note::
 
     The on_change_<field name> methods are runnin in a rollbacked transaction.
 ..
 
 ``on_change_with``
 ------------------
 
 .. attribute:: Field.on_change_with
 
-A list of field names, like :attr:`on_change`, but defined the other way

[udono, 2010/05/07 12:48:31]

... names. Same like...

-around.  If this attribute is set, the client will call the method
+A list of field names. Same like :attr:`on_change`, but defined the other way
+around. If this attribute is set, the client will call the method
 ``on_change_with_<field name>`` of the model when the user changes one of the
-fields defined in the list and will give the values of each fields in this list.
-The method signature is::
+fields defined in the list and will give the values of each fields in this
+list. The method signature is::
 
     on_change_with_<field name>(cursor, user, values[, context])
 
-It must return the new value of the field.

[udono, 2010/05/07 12:48:31]

    This method need to return the new value of the field.

+This method must return the new value of the field.
 
 .. note::
 
     The on_change_with_<field name> methods are running in a rollbacked transaction.
 
 ..
 
 ``depends``
 -----------
 
 .. attribute:: Field.depends
 
 A list of field names on which the current one depends. This means that the
-client will also read those fields even if they are not defined on the view.

[udono, 2010/05/07 12:48:31]

those->these?

+client will also read these fields even if they are not defined on the view.
 :attr:`Field.depends` is used per example to ensure that
 :class:`~trytond.pyson.PYSON` statement could be evaluated.
 
 ``order_field``
 ---------------
 
 .. attribute:: Field.order_field
 
-The name of a substitute field on which the ordering of record must be done

[udono, 2010/05/07 12:48:31]

ordering of records

+The name of a substitute field on which the ordering of records must be done
 instead of this one.
 This is often used to allow ordering on :class:`Function` fields.
 
 ``context``
 -----------
 
 .. attribute:: Field.context
 
 A dictionary which will update the current context when opening a *relation
 field*.
@@ skipping 26 matching lines @@
 ----
 
 .. class:: Char(string[, size[, translate[, \**options]]])
 
 A single line string field.
 
 :class:`Char` has two extra optional arguments:
 
 .. attribute:: Char.size
 
     The maximum length (in characters) of the field. The size is enforced at

[udono, 2010/05/07 12:48:31]

An integer, which defines the maximum count of characters of the field. The
``size``...

     the storage level and in the client input.
 
 .. attribute:: Char.translate
 
     If true, the value of the field is translatable. The value readed and
     stored will depend on the ``language`` defined in the context.
 
 Sha
 ---
 
@@ skipping 25 matching lines @@
 
 .. class:: Float(string[, digits[, \**options]])
 
 A floating-point number field. It will be represented in Python by a ``float``
 instance.
 
 :class:`Float` has one extra optional arguments:
 
 .. attribute:: Float.digits
 
-    A tuple of two integers defining the total of numbers in integer part and

[udono, 2010/05/07 12:48:31]

A tuple of two integers. The first integer defines the total count of digits.
The second integer defines the count of places after the decimal point.

-    the number of decimals.
+    A tuple of two integers. The first integer defines the total of numbers in
+    the integer part. The second integer defines the total of numbers in the
+    decimal part.
     Integers can be replaced by a :class:`~trytond.pyson.PYSON` statement.
 
 Numeric
 -------
 
 .. class:: Numeric(string[, digits[, \**options]])
 
 A fixed-point number field. It will be represented in Python by a
 ``decimal.Decimal`` instance.
 
@@ skipping 29 matching lines @@
 
 .. class:: Binary(string[, \**options])
 
 A binary field. It will be represented in Python by a ``str`` instance.
 
 Selection
 ---------
 
 .. class:: Selection(selection, string[, sort[, translate[, \**options]]])
 
-A string field with limited choice values.

[udono, 2010/05/07 12:48:31]

choice values-> values to choice

+A string field with limited values to choice.
 
 :class:`Selection` has one extra required argument:
 
 .. attribute:: Selection.selection
 
     A list of 2-tuples that looks like this::
 
         [
             ('M', 'Male'),
             ('F', 'Female'),
         ]
 
     The first element in each tuple is the actual value stored. The second
     element is the human-readable name.
 
-    It can also be the name of a method on the model, that will return the

[udono, 2010/05/07 12:48:31]

...return an appropriate list.

-    list. The signature of the method is::
+    It can also be the name of a method on the model, that will return an
+    appropriate list. The signature of the method is::
 
         selection(cursor, user[, context])
 
     .. note::
         The method is automaticly added to :attr:`trytond.model.Model._rpc` if
         not manually set.
     ..
 
 :class:`Selection` has two extra optional arguments:
 
 .. attribute:: Selection.sort
 
     If true, the choices will be sorted by human-readable value. Default value
     is ``True``.
 
 .. attribute:: Selection.translate_selection
 
-    It true, the human-readable values will be translated. Default value is

[udono, 2010/05/07 12:48:31]

It->If

+    If true, the human-readable values will be translated. Default value is
     ``True``.
 
 Reference
 ---------
 
 .. class:: Reference(string[, selection[, \**options]])
 
 A field that refers to a record of a model. It will be represented in Python by
 a ``str`` instance like this::
 
     '<model name>,<record id>'
 
 :class:`Reference` has one extra optional argument:
 
 .. attribute:: Reference.selection
 
     Same as :attr:`Selection.selection` but only for model name.
 
 Many2One
 --------
 
 .. class:: Many2One(model_name, string[, left[, right[, ondelete[, datetime_field[, \**options]]]]])
 
 A many-to-one relation field.
 
 :class:`Many2One` has one extra required argument:
 
 .. attribute:: Many2One.model_name
 
-    The name of the targeted model.

[udono, 2010/05/07 12:48:31]

target model

+    The name of the target model.
 
 :class:`Many2One` has some extra optional arguments:
 
 .. attribute:: Many2One.left
 
     The name of the field that stores the left value for the `Modified Preorder
     Tree Traversal`_.
     It only works if the :attr:`model_name` is the same then the model.
 
 .. _`Modified Preorder Tree Traversal`: http://en.wikipedia.org/wiki/Tree_traversal
 
 .. attribute:: Many2One.right
 
     The name of the field that stores the right value. See :attr:`left`.
 
 .. attribute:: Many2One.ondelete
 
     Define the behavior of the record when the target record is deleted.

[udono, 2010/05/07 12:48:31]

current record

     Allowed values are:
 
         - ``CASCADE``: it will try to delete the record.
 
         - ``RESTRICT``: it will prevent the deletion of the target record.
 
         - ``SET NULL``: it will empty the relation field.

[udono, 2010/05/07 12:48:31]

``SET NULL`` is the default setting.

+
+    ``SET NULL`` is the default setting.
 
     .. note::
         ``SET NULL`` will be override into ``RESTRICT`` if
         :attr:`~Field.required` is true.
     ..
 
 .. attribute:: Many2One.datetime_field
 
     If set, the target record will be read at the date defined by the datetime
     field name of the record.
@@ skipping 27 matching lines @@
       record.
 
     - ``('unlink_all')``: it will unlink all the target records.
 
     - ``('set'[, ids, ...])``: it will link only the target ids to this record.
 
 :class:`One2Many` has some extra required arguments:
 
 .. attribute:: One2Many.model_name
 
-    The name of the targeted model.

[udono, 2010/05/07 12:48:31]

target

+    The name of the target model.
 
 .. attribute:: One2Many.field
 
     The name of the field that handles the opposite :class:`Many2One`
 
 :class:`One2Many` has some extra optional arguments:
 
 .. attribute:: One2Many.add_remove
 
     A :ref:`domain <topics-domain>` to select records to add. If set, the
@@ skipping 24 matching lines @@
 
 .. attribute:: Many2Many.origin
 
     The name of the field that has the :class:`Many2One` to the record.
 
 .. attribute:: Many2Many.target
 
     The name of the field that has the :class:`Many2One` to the target record.
 
 .. note::
-    For :class:`Many2Many` field on simple :class:`~trytond.model.ModelView`,
-    like used in :class:`~trytond.wizard.Wizard`,
-    :attr:`~Many2Many.relation_name` is set to the target model and
-    :attr:`~Many2Many.origin` and :attr:`~Many2Many.target` are set to `None`.

[udono, 2010/05/07 12:48:31]

Sentence complicated. Maybe:

A :class:`Many2Many` field can be used on a simple
:class:`~trytond.model.ModelView`, like in a:class:`~trytond.wizard.Wizard`. For
this,
:attr:`~Many2Many.relation_name` is set to the target model and
:attr:`~Many2Many.origin` and :attr:`~Many2Many.target` are set to `None`.

+    A :class:`Many2Many` field can be used on a simple
+    :class:`~trytond.model.ModelView`, like in a
+    :class:`~trytond.wizard.Wizard`. For this, :attr:`~Many2Many.relation_name`
+    is set to the target model and :attr:`~Many2Many.origin` and
+    :attr:`~Many2Many.target` are set to `None`.
 ..
 
 :class:`Many2Many` has some extra optional arguments:
 
 .. attribute:: Many2Many.order
 
     Same as :attr:`One2Many.order`
 
 .. attribute:: Many2Many.datetime_field
 
     Same as :attr:`Many2One.datetime_field`
 
 Instance methods:
 
 .. method:: Many2Many.get_target(pool)
 
     Return the target :class:`~trytond.model.Model`.
 
 Function
 --------
 
 .. class:: Function(field, getter[, setter[, searcher]])
 
-A function field that can emulate any other given `field`.

[udono, 2010/05/07 12:48:31]

...field can emulate...

+A function field can emulate any other given `field`.
 
 :class:`Function` has a required argument:
 
 .. attribute:: Function.getter
 
     The name of the classmethod of the :class:`~trytond.model.Model` for
     getting values.
     The signature of the method is::
 
         getter(cursor, user, ids, name[, context])
@@ skipping 68 matching lines @@
 
     Same as :meth:`Function.get`.
 
 .. method:: Property.set(cursor, user, ids, model, name, value[, context])
 
     Same as :meth:`Function.set`.
 
 .. method:: Property.search(cursor, user, model, name, clause[, context])
 
     Same as :meth:`Function.search`.