diff options
| -rw-r--r-- | doc/reference/orm.rst | 21 | ||||
| -rw-r--r-- | odoo/fields.py | 67 |
2 files changed, 69 insertions, 19 deletions
diff --git a/doc/reference/orm.rst b/doc/reference/orm.rst index 75e073d2b80..ddc5918553b 100644 --- a/doc/reference/orm.rst +++ b/doc/reference/orm.rst @@ -144,22 +144,27 @@ Advanced Fields Date(time) Fields ''''''''''''''''' -Dates and Datetimes are very important fields in any kind of business -application, they are heavily used in many popular Odoo applications such as -logistics or accounting and their misuse can create invisible yet painful -bugs, this excerpt aims to provide Odoo developers with the knowledge required +:class:`Dates <odoo.fields.Date>` and :class:`Datetimes <odoo.fields.Datetime>` +are very important fields in any kind of business application. +Their misuse can create invisible yet painful bugs, this section +aims to provide Odoo developers with the knowledge required to avoid misusing these fields. When assigning a value to a Date/Datetime field, the following options are valid: * A `date` or `datetime` object. -* A string in the proper server format *(YYYY-MM-DD)* for Date fields, - *(YYYY-MM-DD HH:MM:SS)* for Datetime fields. +* A string in the proper server format: + + * ``YYYY-MM-DD`` for :class:`~odoo.fields.Date` fields, + * ``YYYY-MM-DD HH:MM:SS`` for :class:`~odoo.fields.Datetime` fields. + * `False` or `None`. The Date and Datetime fields class have helper methods to attempt conversion -into a compatible type: :func:`~odoo.fields.Date.to_date` will convert to a `datetime.date` -object while :func:`~odoo.fields.Datetime.to_datetime` will convert to a `datetime.datetime`. +into a compatible type: + +* :func:`~odoo.fields.Date.to_date` will convert to a :class:`datetime.date` +* :func:`~odoo.fields.Datetime.to_datetime` will convert to a :class:`datetime.datetime`. .. admonition:: Example diff --git a/odoo/fields.py b/odoo/fields.py index fc1a225ef34..9919bbc0f48 100644 --- a/odoo/fields.py +++ b/odoo/fields.py @@ -1098,6 +1098,7 @@ class Field(MetaField('DummyField', (object,), {})): class Boolean(Field): + """ Encapsulates a :class:`bool`. """ type = 'boolean' column_type = ('bool', 'bool') @@ -1112,6 +1113,7 @@ class Boolean(Field): class Integer(Field): + """ Encapsulates an :class:`int`. """ type = 'integer' column_type = ('int4', 'int4') @@ -1149,7 +1151,9 @@ class Integer(Field): class Float(Field): - """The precision digits are given by the (optional) digits attribute. + """ Encapsulates a :class:`float`. + + The precision digits are given by the (optional) ``digits`` attribute. :param digits: a pair (total, decimal) or a string referencing a :class:`~odoo.addons.base.models.decimal_precision.DecimalPrecision` record name. @@ -1247,9 +1251,13 @@ class Float(Field): class Monetary(Field): - """ The decimal precision and currency symbol are taken from the attribute + """ Encapsulates a :class:`float` expressed in a given + :class:`res_currency<odoo.addons.base.models.res_currency.Currency>`. + + The decimal precision and currency symbol are taken from the ``currency_field`` attribute. - :param str currency_field: name of the field holding the currency + :param str currency_field: name of the :class:`Many2one` field + holding the :class:`res_currency <odoo.addons.base.models.res_currency.Currency>` this monetary field is expressed in (default: `\'currency_id\'`) """ type = 'monetary' @@ -1528,7 +1536,7 @@ class Char(_String): class Text(_String): - """ Very similar to :class:`~.Char` but used for longer contents, does not + """ Very similar to :class:`Char` but used for longer contents, does not have a size and usually displayed as a multiline text box. :param translate: enable the translation of the field's values; use @@ -1549,6 +1557,18 @@ class Text(_String): class Html(_String): + """ Encapsulates an html code content. + + :param bool sanitize: whether value must be sanitized (default: ``True``) + :param bool sanitize_tags: whether to sanitize tags + (only a white list of attributes is accepted, default: ``True``) + :param bool sanitize_attributes: whether to sanitize attributes + (only a white list of attributes is accepted, default: ``True``) + :param bool sanitize_style: whether to sanitize style attributes (default: ``True``) + :param bool strip_style: whether to strip style attributes + (removed and therefore not sanitized, default: ``False``) + :param bool strip_classes: whether to strip classes attributes (default: ``False``) + """ type = 'html' column_type = ('text', 'text') @@ -1612,9 +1632,7 @@ class Html(_String): class Date(Field): - """ This field type encapsulates a python date object. - :type date: - """ + """ Encapsulates a python :class:`date <datetime.date>` object. """ type = 'date' column_type = ('date', 'date') column_cast_from = ('timestamp',) @@ -1713,9 +1731,7 @@ class Date(Field): class Datetime(Field): - """ This field type encapsulates a python datetime object. - :type datetime: - """ + """ Encapsulates a python :class:`datetime <datetime.datetime>` object. """ type = 'datetime' column_type = ('timestamp', 'timestamp') column_cast_from = ('date',) @@ -1824,6 +1840,11 @@ _BINARY = memoryview class Binary(Field): + """Encapsulates a binary content (e.g. a file). + + :param bool attachment: whether the field should be stored as `ir_attachment` + or in a column of the model's table (default: ``True``). + """ type = 'binary' prefetch = False # not prefetched by default @@ -2007,6 +2028,14 @@ class Binary(Field): class Image(Binary): + """Encapsulates an image, extending :class:`Binary`. + + :param int max_width: the maximum width of the image + :param int max_height: the maximum height of the image + :param bool verify_resolution: whether the image resolution should be verified + to ensure it doesn't go over the maximum image resolution (default: ``True``). + See :class:`odoo.tools.image.ImageProcess` for maximum image resolution (default: ``45e6``). + """ max_width = 0 max_height = 0 verify_resolution = True @@ -2045,7 +2074,8 @@ class Image(Binary): class Selection(Field): - """ + """ Encapsulates an exclusive choice between different values. + :param selection: specifies the possible values for this field. It is given as either a list of pairs ``(value, label)``, or a model method, or a method name. @@ -2249,6 +2279,11 @@ class Selection(Field): class Reference(Selection): + """ Pseudo-relational field (no FK in database). + + The field value is stored as a :class:`string <str>` following the pattern + ``"res_model.res_id"`` in database. + """ type = 'reference' @property @@ -2591,6 +2626,16 @@ class Many2one(_Relational): class Many2oneReference(Integer): + """ Pseudo-relational field (no FK in database). + + The field value is stored as an :class:`integer <int>` id in database. + + Contrary to :class:`Reference` fields, the model has to be specified + in a :class:`Char` field, whose name has to be specified in the + `model_field` attribute for the current :class:`Many2oneReference` field. + + :param str model_field: name of the :class:`Char` where the model name is stored. + """ type = 'many2one_reference' model_field = None |