Fields¶

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 Field.string.

`string`¶

Field.string¶

A string for the label of the field.

`help`¶

Field.help¶

A multi-line help string for the field.

`required`¶

Field.required¶

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

`readonly`¶

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.

`domain`¶

Field.domain¶

A domain constraint that will be applied on the field value.

`states`¶

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 will be evaluated with the values of the record.

`select`¶

Field.select¶

If true, the content of the field will be indexed.

`on_change`¶

Field.on_change¶

A set 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>()

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

Note

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

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

`on_change_with`¶

Field.on_change_with¶

A set of field names. Same like 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 rollbacked transaction.

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

`depends`¶

Field.depends¶

A list of field names on which the current one depends. This means that the client will also read these fields even if they are not defined on the view. Field.depends is used per example to ensure that PYSON statement could be evaluated.

`context`¶

Field.context¶

A dictionary which will update the current context for relation field.

Warning

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

`loading`¶

Field.loading¶

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

`name`¶

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 creation 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)¶: Adds to model the default RPC instances required by the field.

Field.definition(model, language)¶: Returns a dictionary with the definition of the field.

Field.definition_translations(model, language)¶: Returns a list of translation sources used by definition().

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 convert_domain().

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 convert_domain().

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 true/false field.

Integer¶

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

An integer field.

BigInteger¶

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

A long integer field.

Char¶

class trytond.model.fields.Char(string[, size[, translate[, \**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 optional arguments:

Char.size¶: The maximum length (in characters) of the field. The size is enforced at the storage level and in the client input.

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.autocomplete¶

A set of field names. If this attribute is set, the client will call the method autocomplete_<field name> of the model when the user changes one of those field value. The method signature is:

autocomplete_<field name>()

This method must return a list of string that will populate the ComboboxEntry in the client. 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 will be 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 four extra optional 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 will be represented in Python by a float instance.

Float has one extra optional 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 will be done.

Numeric¶

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

A fixed-point number field. It will be represented in Python by a decimal.Decimal instance.

Numeric has one extra optional arguments:

Numeric.digits¶: Same as Float.digits

Date¶

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

A date, represented in Python by a datetime.date instance.

DateTime¶

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

A date and time, represented in Python by a datetime.datetime instance. It is stored in UTC while displayed in the user timezone.

DateTime.format¶: A string format as used by strftime. This format will be 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, represented in Python by a datetime.datetime instance.

Time¶

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

A time, represented in Python by a datetime.time instance.

Time.format¶: Same as DateTime.format

TimeDelta¶

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

An interval, represented in Python by a datetime.timedelta instance.

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. It will be represented in Python by a bytes instance.

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 three extra optional 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 one extra required argument:

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 will return 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 has two extra optional arguments:

Selection.sort¶: If true, the choices will be sorted by human-readable value. Default value is True.

Selection.selection_change_with¶: A set of field names. If this attribute is set, the client will call the selection method of the model when the user changes on of the fields defined in the list and will give the values of each fields in the list. The selection method should be an instance method. The set of field names could be 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.

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 will use the language defined in the context of the instance accessed.

MultiSelection¶

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

A list field with limited values to choose from.

MultiSelection has one extra required argument:

MultiSelection.selection¶: Same as Selection.selection

MultiSelection has two extra optional arguments:

MultiSelection.sort¶: Same as Selection.sort

MultiSelection.translate_selection¶: Same as Selection.translate_selection

MultiSelection.help_selection¶: Same as Selection.help_selection

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 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>'

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

Reference has three extra optional 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¶: Same as Many2One.search_order

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.

Many2One¶

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

A many-to-one relation field.

Many2One has one extra required argument:

Many2One.model_name¶: The name of the target model.

Many2One has some extra optional arguments:

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.ondelete¶

Define the behavior of the record when the target record is deleted. 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.

SET NULL is the default setting.

Note

SET NULL will be 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 trytond.model.ModelSQL._history to request a value for a given date and time on a historicized model.

Many2One.target_search¶

Define the kind of SQL query to use when searching on related target. Allowed values are:

subquery: it will use a subquery based on the ids.

join: it will add a join on the main query.

join is the default value.

Note

join could improve the performance if the target has a huge amount of records.

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.

Beware that search_context will override 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. It requires to have the opposite Many2One field or a Reference field defined on the target model.

This field accepts as written value a list of tuples like this:

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

('write'[[, ids, ...], {<field name>: value, ...}, ...]): it will write values to target ids.

('delete'[, ids, ...]): it will delete the target ids.

('add'[, ids, ...]): it will link the target ids to this record.

('remove'[, ids, ...]): it will unlink the target ids from this record.

('copy', ids[, {<field name>: value, ...}]): it will 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 required 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 optional 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. 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.

This field accepts as written value a list of tuples like the One2Many.

Many2Many has some extra required 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 optional 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.

Warning

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

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]])¶

A function field can emulate any other given field.

Function has a required argument:

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 has some extra optional arguments:

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 will not be 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.

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 one extra required argument:

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_]])¶: Returns 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.

Fields¶

Field options¶

string¶

help¶

required¶

readonly¶

domain¶

states¶

select¶

on_change¶

on_change_with¶

depends¶

context¶

loading¶

name¶

Default value¶

Searching¶

Ordering¶

Depends¶

Field types¶

Boolean¶

Integer¶

BigInteger¶

Char¶

Text¶

FullText¶

Float¶

Numeric¶

Date¶

DateTime¶

Timestamp¶

Time¶

TimeDelta¶

Binary¶

Selection¶

MultiSelection¶

Reference¶

Many2One¶

One2Many¶

Many2Many¶

One2One¶

Function¶

MultiValue¶

Dict¶

`string`¶

`help`¶

`required`¶

`readonly`¶

`domain`¶

`states`¶

`select`¶

`on_change`¶

`on_change_with`¶

`depends`¶

`context`¶

`loading`¶

`name`¶