Fields

Field

class trytond.model.fields.Field

Fields define the behavior of the data on model’s record.

The following attributes are available to all field types. All are optional except string.

Field.string

A string for the label of the field.

Field.help

A multi-line help string for the field.

Field.required

If True, the field is not allowed to be empty. Default is False.

Field.readonly

If True, the field is not editable in the client. Default is False.

Warning

For relational fields, it means only the new, delete, add and remove buttons are inactivated. The editable state of the target record must be managed at the target model level.

Field.domain

A domain constraint that is applied on the field value.

The domain is enforced unless the field value is None.

Note

For Reference field it is a dictionary that contains the domain per model name.

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 PYSON statements that is evaluated with the values of the record.

Field.on_change

A set of field names.

If this attribute is set, the client calls 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>()

This method must change the value of the fields to be updated.

Note

The on_change_<field name> methods are running in a readonly transaction.

The set of field names is filled by using the decorator depends().

Field.on_change_with

A set of field names.

Same as 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:

on_change_with_<field name>()

This method must return the new value of the field.

Note

The on_change_with_<field name> methods are running in a readonly transaction.

The set of field names is filled by using the decorator depends().

Field.depends

A set of extra field names on which the field depends.

This means that the client read also these fields even if they are not defined on the view. Field.depends is used for example to ensure that PYSON statement could be evaluated.

Field.display_depends

A computed set of field names on which the field depends when being displayed in a read only view.

Field.edition_depends

A computed set of field names on which the field depends when being displayed in a writable view.

Field.validation_depends

A computed set of field names on which the field depends when being validated.

Field.context

A dictionary which updates the current context for relation field.

Warning

The context could only depend on direct field of the record and without context.

Field.loading

Define how the field must be loaded: lazy or eager.

Field.name

The name of the field.

Instance methods:

Field.convert_domain(domain, tables, Model)

Convert the simple domain clause into a SQL expression or a new domain. tables could be updated to add new joins.

Field.sql_format(value)

Convert the value to use as parameter of SQL queries.

Field.sql_type()

Return the namedtuple(‘SQLType’, ‘base type’) which defines the SQL type to use for definition and casting. Or None if the field is not stored in the database.

sql_type is using the _sql_type attribute to compute its return value. The backend is responsible for the computation.

For the list of supported types by Tryton see backend types.

Field.sql_cast(expression)

Return the SQL expression with cast with the type of the field.

Field.sql_column(table)

Return the Column instance based on table.

Field.set_rpc(model)

Add to model the default RPC instances needed by the field.

Field.definition(model, language)

Return a dictionary with the definition of the field.

Field.definition_translations(model, language)

Return a list of translation sources used by definition().

Field.searchable(model)

Return True if the field is searchable.

Field.sortable(model)

Return True if the field is sortable.

Default value

See default value

Searching

A class method could be defined for each field which must return a SQL expression for the given domain instead of the default one. The method signature is:

domain_<field name>(domain, tables)

Where domain is the simple domain clause and tables is a nested dictionary, see tables.

Ordering

A class method could be defined for each field which must return a list of SQL expression on which to order instead of the field. The method signature is:

order_<field name>(tables)

Where tables is a nested dictionary, see tables.

Depends

trytond.model.fields.depends([\*fields[, methods]])

A decorator to define the field names on which the decorated method depends.

The methods argument can be used to duplicate the field names from other decorated methods. This is useful if the decorated method calls another method.

Field types

Boolean

class trytond.model.fields.Boolean(string[, \**options])

A boolean field.

Integer

class trytond.model.fields.Integer(string[, \**options])

An integer field.

Char

class trytond.model.fields.Char(string[, size[, translate[, strip[, \**options]]]])

A single line string field.

Search by similarity is used for the ilike operator and is_full_text() value if the backend supports it and a threshold is set. The similarity threshold is defined for the context key <model name>.<field name>.search_similarity or search_similarity.

The field is ordered using the similarity with the context value from the key <model name>.<field name>.order if it is set.

Char has some extra arguments:

Char.size

The maximum length (in characters) of the field. The size is enforced at the storage level and in the client input. The value can be a PYSON statement.

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.

Char.strip

If True, leading and trailing whitespace are removed. If leading, leading whitespace are removed. If trailing, trailing whitespace are removed. The default value is True.

Char.autocomplete

A set of field names.

If this attribute is set, the client calls the method autocomplete_<field name> of the model when the user changes one of those field values. The method signature is:

autocomplete_<field name>()

This method must return a list of string that is used by the client to make autocompletion proposal. The set of field names could be filled by using the decorator depends().

Char.search_unaccented

If this attribute is set to True, ilike searches is performed on unaccented strings. The default value is True.

Warning

The database backend must supports unaccented search.

Char.search_full_text

If this attribute is set to True, ilike searches with an is_full_text() value use the full text search of the backend. The default value is False.

The context can be used to force the full text search behaviour. This is done using the key <model name>.<field name>.search_full_text. If True, the full text search is used no matter what the value. If False, no full text search is peformed.

The full text ranking value is added to the similarity if the search_full_text is True.

Note

The database backend must support full text search otherwise ilike is always used.

Text

class trytond.model.fields.Text(string[, size[, translatable[, \**options]]])

A multi line string field.

Text has some extra arguments:

Text.size

Same as Char.size.

Text.translate

Same as Char.translate.

Text.search_unaccented

Same as Char.search_unaccented.

Text.search_full_text

Same as Char.search_full_text. The default value is True.

FullText

class trytond.model.fields.FullText(\**options)

An internal field to store a list of parsed strings ordered by weights. The field is ordered using the full text ranking with the context value from the key <model name>.<field name>.order if it is set.

Float

class trytond.model.fields.Float(string[, digits[, \**options]])

A floating-point number field. It is represented in Python by a float instance.

Float has some extra arguments:

Float.digits

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 PYSON statement. If digits is None or any values of the tuple is None, no validation on the numbers is done. The tuple can be replaced by a string containing the name of a Many2One pointing to a DigitsMixin.

Numeric

class trytond.model.fields.Numeric(string[, digits[, \**options]])

A fixed-point number field.

Numeric has some extra arguments:

Numeric.digits

Same as Float.digits.

Date

class trytond.model.fields.Date(string[, \**options])

A date field.

Instance methods:

Date.sql_cast(expression[, timezone])

Return the SQL expression cast as date.

If timezone is set the expression is first converted to this timezone.

DateTime

class trytond.model.fields.DateTime(string[, format, \**options])

A date and time field.

It is stored in UTC while displayed in the user timezone.

DateTime has some extra arguments:

DateTime.format

A string format as used by strftime().

This format is used to display the time part of the field. The default value is %H:%M:%S. The value can be replaced by a PYSON statement.

Timestamp

class trytond.model.fields.Timestamp(string[, \**options])

A timestamp field.

Time

class trytond.model.fields.Time(string[, format, \**options])

A time field.

Time has some extra arguments:

Time.format

Same as DateTime.format.

TimeDelta

class trytond.model.fields.TimeDelta(string[, converter[, \**options]])

An interval field.

TimeDelta has some extra arguments:

TimeDelta.converter

The name of the context key containing the time converter.

A time converter is a dictionary with the keys: s (second), m (minute), h (hour), d (day), w (week), M (month), Y (year) and the value in second.

Binary

class trytond.model.fields.Binary(string[, \**options])

A binary field.

Warning

If the context contains a key composed of the model name and field name separated by a dot and its value is the string size then the read value is the size instead of the content.

Binary has some extra arguments:

Binary.filename

Name of the field that holds the data’s filename.

Default value is an empty string, which means the data has no filename (in this case, the filename is hidden, and the “Open” button is hidden when the widget is set to “image”).

Binary.file_id

Name of the field that holds the FileStore identifier.

Default value is None which means the data is stored in the database. The field must be on the same table and accept char values.

Warning

Switching from database to file-store is supported transparently. But switching from file-store to database is not supported without manually upload to the database all the files.

Binary.store_prefix

The prefix to use with the FileStore.

Default value is None which means the database name is used.

Selection

class trytond.model.fields.Selection(selection, string[, sort[, selection_change_with[, translate[, help_selection[, \**options]]]]])

A string field with limited values to choose from.

Selection has some extra arguments:

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 class or instance method on the model, that returns an appropriate list. The signature of the method is:

selection()

Note

The method is automaticly added to trytond.model.Model.__rpc__ if not manually set.

Selection.sort

If True, the choices is sorted by human-readable value.

Default value is True.

Note

If it is False, search results ordered by the field uses the index of the selection instead of the human-readable name.

Selection.selection_change_with

A set of field names.

If this attribute is set, the client calls the selection method of the model when the user changes on of the fields defined in the list and gives the values of each fields in the list.

The selection method should be an instance method.

The set of field names is filled by using the decorator depends().

Selection.translate_selection

If True, the human-readable values will be translated.

Default value is True.

Selection.help_selection

A dictionary mapping the selection value with its help string.

Class methods:

classmethod Selection.get_selection(model, name, inst)

Returns a dictionary mapping the selection value to its human-readable value.

classmethod Selection.get_selection_string(selection, value)

Returns the human-readable form of value in regard to selection. selection is acquired thanks to Selection.get_selection(). ..note:: This method should be used instead of relying on dictionary access because this method take into account the internal representation of the Selection value.

Instance methods:

Selection.translated([name])

Returns a descriptor for the translated value of the field.

The descriptor must be used on the same class as the field. It uses the language defined in the context of the instance accessed.

MultiSelection

class trytond.model.fields.MultiSelection(selection, string[, sort[, translate[, help_selection[, \**options]]]])

A tuple field with limited values to choose from.

MultiSelection has some extra arguments:

MultiSelection.selection

Same as Selection.selection.

MultiSelection.sort

Same as Selection.sort.

MultiSelection.translate_selection

Same as Selection.translate_selection.

MultiSelection.help_selection

Same as Selection.help_selection.

Class methods:

classmethod MultiSelection.get_selection(model, name, inst)

Same as Selection.get_selection()

classmethod MultiSelection.get_selection_string(selection, value)

Same as Selection.get_selection_string()

Instance methods:

MultiSelection.translated([name])

Same as Selection.translated() but returns a list of translated values.

Reference

class trytond.model.fields.Reference(string[, selection[, sort[, selection_change_with[, translate[, help_selection[, search_order[, search_context[, \**options]]]]]]]])

A string field that refers to a record of a model.

‘<model name>,<record id>’

But a tuple can be used to search or set value.

Reference has some extra arguments:

Reference.selection

Same as Selection.selection but only for model name.

Reference.sort

Same as Selection.sort.

Reference.selection_change_with

Same as Selection.selection_change_with.

Reference.translate_selection

Same as Selection.translate_selection.

Reference.help_selection

Same as Selection.help_selection.

Reference.datetime_field

Same as Many2One.datetime_field.

Reference.search_order

A dictionary that contains a PYSON expression defining the default order used to display search results in the clients per model name.

Reference.search_context

Same as Many2One.search_context.

Instance methods:

Reference.translated([name])

Same as translated() but for the translated name of the target model.

Reference.sql_id(column, Model)

Return the SQL expression that extract the record ID of the column.

Many2One

class trytond.model.fields.Many2One(model_name, string[, left[, right[, path[, ondelete[, datetime_field[, search_order[, search_context[, \**options]]]]]]]])

A many-to-one relation field that refers to a record of the named model.

A integer as id is used for low level APIs.

Many2One has some extra arguments:

Many2One.model_name

The name of the target model.

Many2One.left

The name of the field that stores the left value for the Modified Preorder Tree Traversal. It only works if the model_name is the same then the model.

Warning

The MPTT Tree will be rebuild on database update if one record is found having left or right field value equals to the default or NULL.

Many2One.right

The name of the field that stores the right value. See left.

Many2One.path

The name of the Char field that stores the path. It only works if the model_name is the same as the model.

Note

The path is used to optimize searches using the child_of or parent_of operators.

Warning

The paths in the tree will be rebuilt during the database update if any of the records are found to have a path field equal to the default, or NULL.

Many2One.ondelete

Define the behavior of the record when the target record is deleted.

Allowed values are:

• CASCADE: tries to delete the record.

• RESTRICT: prevents the deletion of the target record.

• SET NULL: clears the relation field.

SET NULL is the default setting.

Note

SET NULL is override into RESTRICT if required is True.

Many2One.datetime_field

If set, the target record will be read at the date defined by the datetime field name of the record.

It is usually used in combination with _history to request a value for a given date and time on a historicized model.

Many2One.search_order

A PYSON expression defining the default order used to display search results in the clients.

Many2One.search_context

A dictionary defining the default context used when searching from the client.

Note

search_context overrides the values from the client context.

One2Many

class trytond.model.fields.One2Many(model_name, field, string[, add_remove[, order[, datetime_field[, size[, search_order[, search_context[, \**options]]]]]]])

A one-to-many relation field that refers to records of the named model.

It requires to have the opposite Many2One field or a Reference field defined on the target model.

A tuple composed of integer as id is used for low level APIs.

One2Many accepts as written and created value a list of tuples like this:

• ('create', [{<field name>: value, ...}, ...]): create new target records and link them to this one.

• ('write', ids, {<field name>: value, ...}, ...): write values to target ids.

• ('delete', ids): delete the target ids.

• ('add', ids): link the target ids to this record.

• ('remove', ids): unlink the target ids from this record.

• ('copy', ids[, {<field name>: value, ...}, ...]): copy the target ids to this record. Optional field names and values may be added to override some of the fields of the copied records.

Note

PYSON statement or Field.depends of target records can access value of the parent record fields by prepending _parent_ to the opposite field name and followed by the dotted notation.

One2Many has some extra arguments:

One2Many.model_name

The name of the target model.

One2Many.field

The name of the field that handles the opposite Many2One or Reference.

One2Many has some extra arguments:

One2Many.add_remove

A domain to select records to add.

If set, the client will allow to add/remove existing records instead of only create/delete.

One2Many.filter

A domain that is not a constraint but only a filter on the records.

Warning

Only a static domain is allowed, it cannot contain any PYSON statements.

One2Many.order

A list of tuple defining the default order of the records like for trytond.model.ModelSQL._order.

One2Many.datetime_field

Same as Many2One.datetime_field.

One2Many.size

An integer or a PYSON expression denoting the maximum number of records allowed in the relation.

One2Many.search_order

Same as Many2One.search_order.

One2Many.search_context

Same as Many2One.search_context.

Instance methods:

One2Many.remove(instance, records)

Remove the target records from the instance instead of deleting them.

Many2Many

class trytond.model.fields.Many2Many(relation_name, origin, target, string[, order[, datetime_field[, size[, search_order[, search_context[, \**options]]]]]])

A many-to-many relation field that refers to records of the targeted model.

It requires to have the opposite origin Many2One field or a Reference field defined on the relation model and a Many2One field pointing to the target.

A tuple composed of integer as id is used for low level APIs.

Many2Many accepts as written and created value a list of tuples like the One2Many.

Many2Many has some extra arguments:

Many2Many.relation_name

The name of the relation model.

Many2Many.origin

The name of the field that has the Many2One or Reference to the record.

Many2Many.target

The name of the field that has the Many2One to the target record.

Note

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

Many2Many has some extra arguments:

Many2Many.order

Same as One2Many.order.

Many2Many.datetime_field

Same as Many2One.datetime_field.

Many2Many.size

An integer or a PYSON expression denoting the maximum number of records allowed in the relation.

Many2Many.add_remove

An alias to the domain for compatibility with the One2Many.

Many2Many.filter

Same as One2Many.filter.

Many2Many.search_order

Same as Many2One.search_order.

Many2Many.search_context

Same as Many2One.search_context.

Instance methods:

Many2Many.get_relation()

Return the relation Model.

Many2Many.get_target()

Return the target Model.

Many2Many.delete(instance, records):

Delete the target records from the instance instead of removing them.

One2One

class trytond.model.fields.One2One(relation_name, origin, target, string[, datetime_field[, \**options]])

A one-to-one relation field that refers to a record of the targeted model.

Warning

It is on the relation_name Model that the unicity of the couple (origin, target) must be checked.

A integer as id is used for low level APIs.

One2One has some extra arguments:

One2One.datetime_field

Same as Many2One.datetime_field.

One2One.filter

Same as One2Many.filter.

Instance methods:

One2One.get_relation()

Return the relation Model.

One2One.get_target()

Return the target Model.

Function

class trytond.model.fields.Function(field, getter[, setter[, searcher[, getter_with_context]]])

A function field can emulate any other given field.

Function has some extra arguments:

Function.getter

The name of the classmethod or instance of the Model for getting values. The signature of the classmethod is:

getter(instances, name)

where name is the name of the field, and it must return a dictionary with a value for each instance.

Or the signature of the classmethod is:

getter(instances, names)

where names is a list of name fields, and it must return a dictionary containing for each names a dictionary with a value for each instance.

The signature of the instancemethod is:

getter(name)

where name is the name of the field, and it must return the value.

Function.setter

The name of the classmethod of the Model to set the value. The signature of the method id:

setter(instances, name, value)

where name is the name of the field and value the value to set.

Warning

The modifications made to instances are not saved automatically.

Function.searcher

The name of the classmethod of the Model to search on the field. The signature of the method is:

searcher(name, clause)

where name is the name of the field and clause is a domain clause. It must return a list of domain clauses but the operand can be a SQL query.

Function.getter_with_context

A boolean telling if the getter result depends on the context.

If it does not depend, the getter is called without context and the result is stored in the transaction cache when readonly.

The default value is True.

Instance methods:

Function.get(ids, model, name[, values])

Call the getter classmethod where model is the Model instance of the field, name is the name of the field.

Function.set(ids, model, name, value)

Call the setter classmethod where model is the Model instance of the field, name is the name of the field, value is the value to set.

Function.search(model, name, clause)

Call the searcher classmethod where model is the Model instance of the field, name is the name of the field, clause is a clause of domain.

MultiValue

class trytond.model.fields.MultiValue(field)

A multivalue field that is like a Function field but with predefined getter and setter that use the MultiValueMixin for stored values.

Warning

The get_multivalue() and set_multivalue() should be prefered over the descriptors of the field.

Warning

The default method of the field must accept pattern as keyword argument.

Dict

class trytond.model.fields.Dict(schema_model[, \**options])

A dictionary field with predefined keys.

Note

It is possible to store the dict as JSON in the database if the backend supports by manually altering the column type to JSON on the database.

Dict has some extra arguments:

Dict.schema_model

The name of the DictSchemaMixin model that stores the definition of keys.

Dict.search_unaccented

Same as Char.search_unaccented but when searching on key’s value.

Instance methods:

Dict.translated([name[, type_]])

Return a descriptor for the translated values or keys of the field following type_. The descriptor must be used on the same class as the field. Default type_ is values.