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 isFalse
.
- Field.readonly#
If
True
, the field is not editable in the client. Default isFalse
.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
andinvisible
. The values arePYSON
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 methodon_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 thatPYSON
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
oreager
.
- Field.name#
The name of the field.
- Field._type#
The type of the field.
- Field._sql_type#
The SQL type of the field.
- Field._py_type#
The Python type 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.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#
Integer#
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 andis_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
orsearch_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 thelanguage
defined in the context.
- Char.strip#
If
True
, leading and trailing whitespace are removed. Ifleading
, leading whitespace are removed. Iftrailing
, trailing whitespace are removed. The default value isTrue
.
- Char.autocomplete#
A set of field names.
If this attribute is set, the client calls the method
autocomplete_<field name>
of themodel
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 isTrue
.Warning
The database backend must supports unaccented search.
- Char.search_full_text#
If this attribute is set to
True
,ilike
searches with anis_full_text()
value use the full text search of the backend. The default value isFalse
.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
. IfTrue
, the full text search is used no matter what the value. IfFalse
, no full text search is peformed.The full text ranking value is added to the similarity if the
search_full_text
isTrue
.Note
The database backend must support full text search otherwise
ilike
is always used.
Instance methods:
- Char.translated([name])#
Returns a descriptor to a method that returns the translated value of the field. If no lanaguage code is provided when calling the method, the
trytond.transaction.Transaction.language
is used.The descriptor must be used on the same class as the field.
Text#
- class trytond.model.fields.Text(string[, size[, translatable[, \**options]]])#
A multi line
string
field.
Text
has some extra arguments:
- 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 isTrue
.
Instance methods:
- Text.translated([name])#
Same as
Char.translated()
.
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 afloat
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 isNone
or any values of the tuple isNone
, no validation on the numbers is done. The tuple can be replaced by a string containing the name of aMany2One
pointing to aDigitsMixin
.
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#
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 aPYSON
statement.
Timestamp#
Time#
Time
has some extra arguments:
- Time.format#
Same as
DateTime.format
.
TimeDelta#
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 acceptchar
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 toselection
.selection
is acquired thanks toSelection.get_selection()
. ..note:: This method should be used instead of relying on dictionary access because this method take into account the internal representation of theSelection
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.
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.path#
The name of the
Char
field that stores the path. It only works if themodel_name
is the same as the model.Note
The path is used to optimize searches using the
child_of
orparent_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 intoRESTRICT
ifrequired
isTrue
.
- 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 clientcontext
.
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 aReference
field defined on the target model.A
tuple
composed ofinteger
asid
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
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 aReference
field defined on the relation model and aMany2One
field pointing to the target.A
tuple
composed ofinteger
asid
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
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.filter#
Same as
One2Many.filter
.
- Many2Many.search_order#
Same as
Many2One.search_order
.
- Many2Many.search_context#
Same as
Many2One.search_context
.
Instance methods:
- 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.
One2One
has some extra arguments:
- One2One.datetime_field#
Same as
Many2One.datetime_field
.
- One2One.filter#
Same as
One2Many.filter
.
Instance methods:
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.
Note
The getter function is called with the
_context
of the instances.
- 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 andvalue
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 andclause
is a domain clause. It must return a list of domain clauses but theoperand
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 wheremodel
is theModel
instance of the field,name
is the name of the field.
MultiValue#
- class trytond.model.fields.MultiValue(field)#
A multivalue field that is like a
Function
field but with predefinedgetter
andsetter
that use theMultiValueMixin
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
orkeys
of the field followingtype_
. The descriptor must be used on the same class as the field. Defaulttype_
isvalues
.
fmany2one#
- trytond.model.fields.fmany2one(name, sources, target[, string[, ondelete[, \**options]]])#
Return a mixin class which adds a Function
field to a
ModelSQL
class that emulate a Many2One
that
refers to the target
record having the sources
as value.
target
is composed of the name of the model and the name of the fields
separated by a comma.
The target fields must be unique.